PromptOwl + ContextNest Docs
Contents

CLI Reference

Updated Open in ChatGPTOpen in Claude

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

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:

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.

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:

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

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 and 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 pages

  • Vault Registry & Multi-VaultContextNest keeps a central vault registry so you can work with many nests from any directory. The registry maps a short alias to a nest — a local path or…
  • Remote & Governed NestsA nest does not have to live on your local disk. ContextNest can register remote nests and route reads and writes to them over MCP — the same ctx commands…
  • Authentication & API KeysContextNest Community distinguishes two kinds of key, and it is worth keeping them straight:
  • Vault & Registry ConfigurationContext Nest reads configuration from two places: The central registry holds a vaults: map (alias → local vault), an optional remotes: map (alias → hosted…
  • Install the ctx CLIThe package installs with a flattened dependency tree — its runtime dependencies are bundled/flattened so a global install pulls a self-contained CLI…

Referenced by