# The CLI

> Every capabilities hub command and the milestone that brings it, plus the census and stack commands that exist in the repository today.

Canonical page: https://capabilities.sh/docs/cli
Updated: 2026-11-06

One binary, `capabilities`, holds three surfaces. `capabilities hub` runs the hub and is planned for M1. The census commands and the `capabilities stack` preview exist in the repository today, but the CLI is private and unreleased.

> [!PLANNED]
> No `capabilities hub` command runs yet. The M1 commands arrive with plan units LH-13, LH-14 and LH-15. Commands marked "later" wait for later plans.

## capabilities hub

### Setup

| Command                            | What it does                                                         | Arrives |
| ---------------------------------- | -------------------------------------------------------------------- | ------- |
| `init [--import]`                  | Create the hub; with `--import`, run the importer too                 | M1      |
| `import [--from <harness>…]`       | Read harness configs and propose sources and credentials              | M1      |
| `add <ref> [--namespace <name>]`   | Add one source from a URL or a stdio command line                      | M1      |
| `list`                             | List sources                                                          | M1      |
| `remove <namespace>`               | Remove a source                                                       | M1      |
| `refresh [namespace]`              | Re-read tool lists and detect tools that changed upstream             | M1      |
| `review`                           | Decide new and changed tools                                          | M1      |
| `connect [--client …] [--replace]` | Point your harnesses at the hub                                       | M1      |
| `disconnect`                       | Undo `connect`                                                        | M1      |

### Credentials and access

| Command                                  | What it does                                | Arrives |
| ---------------------------------------- | ------------------------------------------- | ------- |
| `connections <namespace>`                | List a source's connections                 | M1      |
| `auth <namespace> [--connection <name>]` | Enter a credential at a masked prompt       | M1      |
| `policy …`                               | Edit policy rules                           | Later   |
| `profiles …`                             | Manage profiles beyond `default`            | Later   |

### Serving and running

| Command                                    | What it does                                    | Arrives |
| ------------------------------------------ | ----------------------------------------------- | ------- |
| `serve --stdio`                            | Serve the MCP endpoint to a harness             | M1      |
| `serve --http [--port <n>]`                | Serve on loopback for clients that prefer HTTP  | M1      |
| `call <address> '<json>'`                  | Call one tool from the terminal                 | M1      |
| `exec '<code>'`                            | Run code from the terminal                      | M1      |
| `runs [--status <s>]`, `runs show <id>`    | List runs, or show one                          | M1      |
| `approve <runId>`                          | Decide a pending call and resume the run        | M1      |
| `cancel <runId>`                           | Cancel a run                                    | M1      |
| `doctor`                                   | Diagnose sources, the store and the keychain    | M1      |

`serve --stdio` is what harness configs launch: each harness session gets its own process, and all of them share the store under `~/.capabilities/hub/`. `serve --http` binds only to loopback, on port 4790 by default, and requires the bearer token in `~/.capabilities/hub/http-token` (mode 600). In M1, `--profile` accepts only `default`.

### Hosted

| Command            | What it does                                        | Arrives      |
| ------------------ | --------------------------------------------------- | ------------ |
| `login`            | Sign in to the hosted hub                           | Later, M3    |
| `push [--secrets]` | Send your local configuration to the hosted hub     | Later, M3    |
| `status`           | Show the hosted hub's state                         | Later, M3    |

`push` sends sources, policies, profiles, skill files and connection metadata, never secret values, unless you pass `--secrets` and consent to each one. The server answers with a plan and its hash, and applying needs that hash.

## Where the hub keeps its files

```text
~/.capabilities/hub/          mode 700; every file 600
  hub.json                    settings, schema version, hub id
  sources/  manifests/  connections/  policies/  profiles/  skills/
  runs/<id>.json              one record per run
  runs/<id>.journal.jsonl     append-only journal of the run's calls
  blobs/  locks/
  http-token                  bearer token for serve --http
```

Writes go to a temporary file, are synced, and are renamed into place. Several `serve --stdio` processes share the store through per-record lock files, not a daemon.

## The CLI today

These commands exist in the repository and run from a checkout build. They manage capabilities across your coding agents, and the hub builds on them.

| Command                              | What it does                                                  |
| ------------------------------------ | ------------------------------------------------------------- |
| `capabilities list`                  | Show installed capabilities                                   |
| `capabilities doctor`                | Check for missing secrets and broken client configs           |
| `capabilities rollback`              | Restore client configs from the last snapshot                 |
| `capabilities login`                 | Sign in with GitHub (device flow)                             |
| `capabilities stack init`            | Link the stack repository that syncs your capabilities        |
| `capabilities stack push`            | Commit your stack and push it to the stack repository         |
| `capabilities stack pull`            | Apply the stack repository's capabilities to this machine     |
| `capabilities stack install <slug>`  | Install a capability into your coding agents                  |
| `capabilities stack uninstall <ref>` | Remove a capability from your clients and the lock            |

Two global options go before the command: `--registry <dir|url>` and `--no-input`. Secret values never enter the lockfile. They are read from your shell environment, then the OS keychain, then `~/.capabilities/.env`.

```sh
pnpm --filter capabilities dev --help
pnpm --filter capabilities dev list
pnpm --filter capabilities dev doctor
```