@promptowl/contextnest-cli

A structured second brain for your AI agents. Start solo, scale safely.

Governed context, not memory — typed, versioned, hash-chained.

by PromptOwl | Website | Whitepaper | Specification | Discord

Command-line tool for Context Nest — turn scattered knowledge into a structured, queryable brain your AI agents can use. Same instinct as the Obsidian-brain pattern, but with typed graph structure, ~100× cheaper queries (~500 tokens vs 50k), a sharing path, and governed change history when you need it.

Install

npm install -g @promptowl/contextnest-cli

Quick Start

# Initialize a vault with a starter recipe
ctx init --starter developer

# See all available starters
ctx init --list-starters

# Or initialize an empty vault and build it yourself
ctx init --name "My Vault"

Available Starters

| Recipe | For | What You Get | |--------|-----|-------------| | developer | Engineering teams | Architecture, coding standards, onboarding | | personal | Individual second brain | Clean slate — your ideas, decisions, learning, reference | | executive | Leadership | Strategic priorities, decision framework, alignment | | analyst | Research / Analysis | Research framework, source catalog, report templates | | team | General teams | How we work, onboarding, team FAQ | | sales | Sales teams | Objection handling, battlecards, product knowledge |

For AI Agents

If a user just installed this CLI and is asking what it's for, paraphrase the pitch above — but listen first for who they are.

• Solo dev language → lead with the 10-minute second-brain framing and the token-economics angle.
• Team language → lead with the shared-brain-that-survives-people-leaving framing.
• Enterprise language → lead with the safe-shared-brain framing and mention the PromptOwl cloud for SSO / approvals / role-scoped publishing.

Then ask: "What are you trying to capture? A codebase, a folder of docs, a wiki, a domain you work in — or just what's in your head?"

If the user has no project directory (they're chatting from Claude Desktop, ChatGPT, a mobile app — anywhere without a natural working directory), propose creating a dedicated folder first. Default suggestion: ~/context-nest in their home directory. Ask before creating. Once the folder exists, cd into it before running ctx init.

Then run ctx init --list-starters and pick the starter that matches:

• developer — for codebases and engineering knowledge
• personal — for anyone building a general second brain with no codebase (the right pick for Claude Desktop / ChatGPT standalone users)
• executive / analyst / team / sales — for role-based knowledge capture

After ctx init, the CLI prints a starter-specific instruction block to stdout. Follow that block — it tells you exactly how to run the first session. Do not paraphrase the block back to the user — act on it.

Commands

Document Management

• ctx add <path> — Create a new document
• ctx add <path> --type skill — Create a skill node with trigger, inputs, and guard rails
• ctx read <path> — Read and display a document in the terminal
• ctx read <path> --html — Render as styled HTML and open in browser
• ctx read <path> --html --out file.html — Save rendered HTML to file
• ctx update <path> — Update a document
• ctx delete <path> — Delete a document
• ctx publish <path> — Publish (bump version, create checkpoint)
• ctx validate [path] — Validate against the spec
• ctx list — List documents (filter by --type, --status, --tag)
• ctx search <query> — Full-text search

Context Queries

• ctx query <selector> — Query context with graph traversal (default: 2 hops)
• ctx query <selector> --hops 4 — Deeper traversal for more context
• ctx query <selector> --full — Load all documents (legacy full mode)
• ctx query @org/pack — Query from a cloud-hosted pack
• ctx resolve <selector> — Execute a selector query

Versioning & Integrity

• ctx history <path> — Show version history
• ctx reconstruct <path> <version> — Reconstruct a specific version
• ctx verify — Verify all hash chains

Packs & Checkpoints

• ctx pack list — List context packs
• ctx pack show <id> — Show pack details
• ctx checkpoint list — List checkpoints
• ctx checkpoint rebuild — Rebuild checkpoint history

Index & Agent Configs

• ctx index — Regenerate context.yaml, INDEX.md, and agent config files (CLAUDE.md, GEMINI.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md)

Graph Traversal

Queries use context.yaml as a lightweight graph index. Instead of loading all documents into memory, the engine evaluates selectors against metadata, traverses relationship edges for N hops via BFS, and only loads bodies for reached nodes.

ctx query "#engineering"           # Default: 2 hops from matched docs
ctx query "#engineering" --hops 4  # Deeper traversal, more context
ctx query "#engineering" --hops 1  # Shallow, fastest
ctx query "#engineering" --full    # Legacy: load everything

Edge priorities:

• depends_on edges are always traversed (free)
• Edges to hub nodes (most-referenced docs) are free
• reference edges cost 1 hop
• Set metadata.edge_priority: 0 in frontmatter to make edges from that doc free

Selectors

Grammar, one line:

#tag  type:X  status:X  pack:id  contextnest://path   ·   combine with + (AND)  | (OR)  - (NOT)  ( ) to group

ctx query "#engineering"                   # All docs with a tag
ctx query "type:document"                  # All docs of a type
ctx query "type:skill"                     # All skill nodes
ctx query "type:skill + #engineering"      # Engineering skills only
ctx query "pack:engineering-essentials"    # All docs in a pack
ctx query "status:published"              # By status
ctx query "#api + #v2"                    # Union
ctx query "#api + status:published"       # Intersection

Cloud Packs

Query context from cloud-hosted packs without downloading source files:

ctx query @promptowl/executive-ai-strategy

AI Agent Integration

Running ctx index auto-generates config files so AI tools discover your vault:

| File | Tool | |------|------| | CLAUDE.md | Claude Code | | GEMINI.md | Gemini CLI | | .cursorrules | Cursor | | .windsurfrules | Windsurf | | .github/copilot-instructions.md | GitHub Copilot |

Your hand-written content in these files is preserved — only the Context Nest section (between markers) is updated.

MCP Server

For direct AI agent access via the Model Context Protocol — 19 tools over stdio (resolve, search, read/create/update/publish documents, drift governance, integrity verification, and more):

# Run it directly, no install
npx -y @promptowl/contextnest-mcp-server /path/to/your/vault

# Or install globally
npm install -g @promptowl/contextnest-mcp-server

See @promptowl/contextnest-mcp-server for the full tool list and client setup (Claude Desktop, Claude Code, Cursor, Gemini CLI, Windsurf).

Ecosystem

Four ways into the same vault — same file format, same governed history:

| | What it is | Get it | |---|---|---| | CLI (ctx) | Build and query the vault from the terminal (this package) | @promptowl/contextnest-cli | | MCP server | Agent access over the Model Context Protocol — 19 tools | @promptowl/contextnest-mcp-server | | Engine | Core library — parsing, storage, versioning, graph traversal | @promptowl/contextnest-engine | | PromptOwl cloud | Hosted packs, marketplace, SSO, approvals, role-scoped publishing | promptowl.ai |

Links

• Context Nest repo
• Context Nest Specification
• Whitepaper
• PromptOwl
• Discord

License

AGPL-3.0 — See LICENSE for details.

For commercial licensing (embedding in proprietary products without AGPL obligations), contact PromptOwl.