# CLI Reference

The Context Nest CLI (`ctx`) is a structured, versioned knowledge base your AI agents can query. It provides commands for setting up vaults, creating and editing documents, retrieving context, versioning, integrity/governance, and sharing.

> Reference verified against `ctx --version` **2.2.0**. Flags below come from live `ctx <command> --help` output. The vault discovery order, the remote-alias rows, `ctx skill`, `ctx pull`, and the `ctx push` flags were rechecked against the CLI source at **3.0.3**.

## Install

```bash
npm install -g @promptowl/contextnest-cli
```

The package installs two identical binaries: `ctx` and `contextnest`.

## Command groups

Run `ctx --help` for the grouped overview, or `ctx <command> --help` for the exact options of any command.

### Set up a vault

| Command | Description |
|---------|-------------|
| `ctx init` | Create a new vault in the current folder |
| `ctx init --starter <recipe>` | Scaffold from a starter recipe (`developer`, `executive`, `analyst`, `team`, `sales`) |
| `ctx init --list-starters` | List available starter recipes |
| `ctx init --layout <mode>` | Layout mode: `structured` (default) or `obsidian` |
| `ctx init --name <name>` | Vault name (default: "My Context Nest") |
| `ctx init --set-default` | Register the new vault as the registry default |
| `ctx init --description <text>` | Nest description (written to `.context/config.yaml` and the registry entry) |
| `ctx vault …` | Manage the named-vault registry (see below) |
| `ctx welcome` | Regenerate and open the vault's welcome page (`--no-open` to skip the browser) |
| `ctx info` | Show the vault's instructions, configuration, and contents (`--nodes` to list every node, `--json`) |

### Manage named vaults (registry)

`ctx vault` maintains a central registry mapping an **alias → path** so you can target any vault from any folder with the global `--vault <alias>` flag.

| Command | Description |
|---------|-------------|
| `ctx vault list` | List registered vaults (`--json`). Each nest behind a server-level remote is listed as `<alias>/<nest>` |
| `ctx vault add <alias> [path]` | Register a vault path under an alias |
| `ctx vault add <alias> --set-default` | Register and make it the default |
| `ctx vault add <alias> --description <text>` | Attach a short label to the alias |
| `ctx vault add <alias> --url <url> [--bearer-env <var>]` | Register a **remote** nest at a streamable-HTTP MCP endpoint |
| `ctx vault add <alias> --mcp-command <cmd> [--mcp-arg <arg> …]` | Register a **remote** nest served by a stdio MCP command |
| `ctx vault describe <alias> [description]` | Set (or clear) an alias's description |
| `ctx vault remove <alias>` | Unregister an alias (aliases: `rm`) |
| `ctx vault prune` | Unregister local aliases whose vault no longer exists on disk (remotes are left alone) |
| `ctx vault default <alias>` | Set the default vault |
| `ctx vault which` | Show which vault the CLI would use right now, and why (respects `--vault`; `--json`) |

**Hosted nests.** A ContextNest Community server exposes one MCP endpoint per nest (`<server>/nests/<id>/mcp`) and one server-level endpoint (`<server>/mcp`). Register either with `--url`:

```bash
export TEAM_NEST_TOKEN=cnst_...     # a key from the server's Connect dialog
ctx vault add team --url https://nest.example.com/mcp --bearer-env TEAM_NEST_TOKEN
ctx vault list                        # shows team/<nest> for every nest the key can see
ctx --vault team/handbook query "#onboarding"
```

A server-level alias takes a `/<nest>` suffix on `--vault`: `<nest>` is the nest's slugged name (or its id), and `ctx vault list` prints the exact labels. A per-nest alias (`…/nests/<id>/mcp`) is used as-is, with no suffix.

### Sign in to a server

`ctx login` signs you in to a hosted ContextNest server once. The key goes to your operating system's secure store (the macOS Keychain, for example), never into `config.yaml`, and later commands reuse it, so you don't need `--bearer-env`.

```bash
ctx login https://nest.promptowl.ai --as promptowl --set-default
ctx vault list                         # promptowl [server], promptowl/<nest>, ...
```

Your browser opens to approve the login. Over SSH or on a machine with no display, `ctx login` prints the approval link instead, and you open it on any device.

| Command | Description |
|---------|-------------|
| `ctx login <server>` | Browser sign-in; saves a key for the whole server |
| `ctx login <server> --as <alias>` | Also register the server as a remote vault under that alias (all its nests) |
| `ctx login <server> --as <alias> --set-default` | Also make that alias your default vault |
| `ctx login <server> --key-stdin` | Sign in with an existing key (`cnst_...`) read from stdin, for servers without browser login |
| `ctx login <server> --nest <id> --key-stdin` | Save a key that reaches one nest only |
| `ctx login --list` | Show the servers and nests you are signed in to (never prints keys) |
| `ctx logout <server>` | Forget the saved key for a server (it stays valid on the server; revoke it in the web UI) |

**New nests appear on their own.** A server registered with `--as` is stored as one entry. Its nests are not stored: `ctx vault list` asks the server each time (cached for a few minutes), so a nest created on the server, or shared with you later, shows up as `<alias>/<new-nest>` without any local change. An alias registered for a single nest (`<server>/nests/<id>/mcp`) is fixed to that nest and never lists others.

**Read from one nest, or from all of them:**

```bash
ctx --vault promptowl/engineering list              # one nest
ctx --vault promptowl/engineering search "login"
ctx --vault promptowl/engineering query "#adr"
ctx --vault promptowl search "billing"              # every nest on the server (reads only)
```

`<nest>` is the nest's slugged name or its id; `ctx vault list` prints the exact labels. Writes need a named nest, since a bare server alias only lists the choices. If the server cannot be reached, `ctx vault list` shows the last known nests marked "not answering". If it rejects the key, the row says to run `ctx login <server>` again.

### Create & edit documents

| Command | Description |
|---------|-------------|
| `ctx add <path>` | Create a new document with a frontmatter template (this is **version 1**) |
| `ctx add <path> --type <type>` | Node type (default: `document`) |
| `ctx add <path> --title <title>` | Set the document title |
| `ctx add <path> --tags <tags>` | Tags (comma- or space-separated) |
| `ctx add <path> --body <body>` | Markdown body content |
| `ctx add <path> --type skill --trigger <desc>` | Create a skill node with a trigger description |
| `ctx skill show <path>` | Render a skill node for an agent harness and print it (`--harness`, `--server-alias`, `--scope user\|project`) |
| `ctx skill install <path>` | Build the files that install a vault skill locally; add `--write` to write them (`--mode loader` fetches the procedure at runtime and cannot drift, `--mode full` is an offline snapshot) |
| `ctx read <path>` | Show a document (`--raw` for frontmatter+body, `--html` to render/open in the browser, `--out <file>` to save the HTML) |
| `ctx update <path>` | Edit a document, then auto-publish a new version (`--title`, `--tags`, `--status`, `--body`) |
| `ctx delete <path>` | Remove a document and its full version history |

### Find & retrieve context

| Command | Description |
|---------|-------------|
| `ctx list` | Browse documents (`--type`, `--status`, `--tag`, `--limit <n>`, `--json`) |
| `ctx search <query>` | Full-text search across the vault (`--limit <n>`, `--json`) |
| `ctx query <selector>` | Pull context for an agent by selector — graph-aware and token-cheap (`--hops <n>`, `--full`, `--include-drafts`, `--json`) |
| `ctx resolve <selector>` | List the documents a selector matches, metadata only (`--json`) |
| `ctx pack list` | List all context packs |
| `ctx pack show <id>` | Show pack details and resolved documents |

Retrieval returns **published documents only by default**. Add `--include-drafts` to `ctx query` (and to `ctx push`) to include drafts.

### Versions & snapshots

| Command | Description |
|---------|-------------|
| `ctx publish [path]` | Bump a document's version and record a checkpoint (`--all` to publish every unpublished doc in one batch, `--author <email>`, `--message <note>`) |
| `ctx history <path>` | Show a document's version history (`--diff` for per-version unified diffs, `--json`) |
| `ctx reconstruct <path> <version>` | Rebuild a specific past version of a document |
| `ctx checkpoint list` | List vault-wide snapshots |
| `ctx checkpoint rebuild` | Rebuild checkpoint history from per-document histories |

### Integrity & governance

| Command | Description |
|---------|-------------|
| `ctx verify` | Check every hash chain for tampering (`--json`) |
| `ctx validate [path]` | Check documents against the Context Nest spec (`--json`) |
| `ctx drift scan` | Scan the vault for body drift (live file bytes ≠ stored checksum) |
| `ctx drift stage <path>` | Stage a drifted document as a suggestion under `_suggestions/` |
| `ctx drift list <path>` | List staged suggestions for a document |
| `ctx drift approve <path> <suggestionId>` | Approve a suggestion: bump version, write new canonical bytes, archive |
| `ctx drift reject <path> <suggestionId>` | Reject a suggestion: archive without merge |
| `ctx index` | Regenerate `context.yaml` and `INDEX.md`; canonicalize status aliases on disk |

### Share

| Command | Description |
|---------|-------------|
| `ctx push` | Push the local vault to a hosted ContextNest server (`--server <url>`, `--nest <id>`, `--key <apiKey>`, `--include-drafts`; for a nest that gates pushes, `--no-wait` and `--timeout <sec>`) |
| `ctx pull <source> --recipe <id>` | Pull a recipe from a remote nest into the local vault as drafts with lineage (`--update`, `--json`; `--dry-run` prints the plan). `<source>` is a registered remote alias or `<alias>/<nest>` |

For `ctx push`, prefer the `CONTEXTNEST_API_KEY` environment variable over `--key` — argv is visible to other processes. `--server` must be `https://`, or a localhost address.

## Global options

These apply across commands (from `ctx --help`):

| Flag | Description |
|------|-------------|
| `--vault <alias>` | Target a registered vault by alias from any folder |
| `--dry-run` | Preview a write command against a temp copy of the vault and report the real file list without touching yours |
| `-y, --yes` | Skip confirmation prompts |
| `--force` | Allow overwriting existing files |
| `--json` | JSON output (supported by most read commands) |
| `-V, --version` | Print the version number |
| `-h, --help` | Show help |

## File safety & consent

Every command that writes **asks before it does**, then prints the exact list of files it created, modified, or deleted — nothing is overwritten silently. `--dry-run` runs the command against a temp copy of the vault and reports the real file list without touching yours. In a **non-interactive shell** (agents, CI) destructive commands refuse unless `--yes` or `--force` is passed.

## Vault discovery

When no `--vault` alias is given, the CLI resolves the target vault in this order (from the engine's resolver):

1. explicit `--vault <alias>` flag → registry lookup
2. `CONTEXTNEST_VAULT` env (alias) → registry lookup
3. `CONTEXTNEST_VAULT_PATH` env (a direct vault path)
4. a positional path argument
5. a local vault found by walking up from the current directory (nearest `.context/config.yaml`)
6. the registry `default:` alias
7. the current directory, as a last resort

Both env vars are honored: `CONTEXTNEST_VAULT` names a registered **alias**, `CONTEXTNEST_VAULT_PATH` is a **path**. A stale value in either is ignored with a warning rather than blocking every command. See [Configuration](https://nest.promptowl.ai/d/promptowl-documents/protocol/configuration) and [Vault Registry & Multi-Vault](https://nest.promptowl.ai/d/promptowl-documents/protocol/vault-registry/vault-registry-multi-vault).

## Starter recipes

| Recipe | For |
|--------|-----|
| `developer` | Engineering teams |
| `executive` | Strategic leadership |
| `analyst` | Research / OSINT |
| `team` | General team knowledge base |
| `sales` | Sales teams |

Run `ctx init --list-starters` for the authoritative list and each recipe's contents.

## Related

- [Vault Registry & Multi-Vault](https://nest.promptowl.ai/d/promptowl-documents/protocol/vault-registry/vault-registry-multi-vault) — aliases and `--vault`
- [Remote & Governed Nests](https://nest.promptowl.ai/d/promptowl-documents/protocol/remote-nests/remote-governed-nests) — registering hosted and MCP nests
- [Configuration](https://nest.promptowl.ai/d/promptowl-documents/protocol/configuration) — `config.yaml` and environment variables
- [Authentication & API Keys](https://nest.promptowl.ai/d/promptowl-documents/protocol/authentication-api-keys) — the `cnst_` keys `push` and remote aliases use
- [Vault-Hosted Skills](https://nest.promptowl.ai/d/promptowl-documents/protocol/skills/vault-hosted-skills) — skill nodes and `ctx skill`