The CLI

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

Copy as Markdown /docs/cli.md

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.

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

~/.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.

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

Updated 2026-11-06