# cogs command line

Inspect an instance, run explicit engine requests, and understand local-only CLI commands.

Source: https://docs.minds.sh/docs/developers/cli



`cogs` is the Rust command-line client for Akasha. It includes scripting commands and a Control Room terminal interface. The Cargo package is `minds-cli`; the binary is `cogs`, even though some parser help and compatibility code retain the `akasha` name.

## Build from source [#build-from-source]

From the Akasha repository root:

```bash
cargo install --path minds-cli --bin cogs
cogs --help
```

Use your normal approved build environment. This installs a source build; it does not download an unverified prebuilt release.

## Select a connection [#select-a-connection]

Global flags include `--config`, `--base-url`, `--token-env`, and `--no-tui`. An explicit base URL overrides the local configuration. Without `--config`, the parser reads `./akasha-cli.toml` if present and `AKASHA__*` environment variables.

```toml
base_url = "https://<your-instance>.minds.sh"
token_env = "AKASHA_TOKEN"
```

The default token environment variable is `AKASHA_TOKEN`; `--token-env` chooses a different variable name. It is sent through the Rust SDK as a Bearer token. Capability-required instances need an additional `x-akasha-capability` header, which the current CLI transport does not expose. Use the [direct HTTP guide](/docs/developers/quickstart) for those instances rather than weakening the server policy.

## Useful commands on a compatible endpoint [#useful-commands-on-a-compatible-endpoint]

```bash
cogs --base-url "$AKASHA__BASE_URL" --no-tui memory search 'launch review' --limit 5
cogs --base-url "$AKASHA__BASE_URL" --no-tui memory retrieval-hybrid 'launch review' --limit 5
```

The search command expects the episodic search array. Hybrid retrieval sends the daemon's `text` field. Both still need compatible authentication and enabled services.

Raw JSON requests are available when a convenience method does not match the endpoint:

```bash
cogs --base-url "$AKASHA__BASE_URL" --no-tui http post \
  /v1/mcp/tools/list '{}'
```

Raw HTTP supports GET, POST, PUT, and DELETE. The body argument must be JSON. It retains the same CLI authentication transport; it does not add a capability header automatically.

## Command families [#command-families]

| Family                                                   | Work it exposes                                                          |
| -------------------------------------------------------- | ------------------------------------------------------------------------ |
| `storage`, `graph`, `analytics`                          | Engine data and queries                                                  |
| `memory`, `assoc-mhn`, `cognitive`, `cycle`, `continual` | Memory, associative recall, and cognitive operations                     |
| `snn`, `ns`, `ml`                                        | Neural and model-related services                                        |
| `router`, `conductor`, `ocip`                            | Separate gRPC and capability-oriented integrations                       |
| `replication`, `interchange`                             | Data transfer and replication workflows                                  |
| `instances`, `start`, `local`                            | Saved endpoints and local runtime management                             |
| `mcp`                                                    | Local tool introspection, isolated tool tests, and configuration helpers |
| `control-room`, `settings`, `repl`                       | Interactive interfaces                                                   |

The [complete CLI reference](/docs/developers/reference/cli) preserves every parser command, flag, default, and nested action declaration. Some advanced commands depend on enabled build features or external services; inspect their exact declaration and handler before automation.

## Local tests are not connection checks [#local-tests-are-not-connection-checks]

`cogs mcp info`, `mcp tools`, and `mcp test` operate on the local MCP registry. `mcp test` creates an in-memory backend for each call. Its success does not verify a hosted Mind, credential, or persistent record. The current setup helpers also need the correction described in [Compatibility](/docs/developers/compatibility).

Use `cogs control-room` for the existing terminal dashboard, or see [Terminal interfaces](/docs/developers/tui) for the separate `mind` chat application.