npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@promptowl/contextnest-cli

v3.7.1

Published

CLI for governed, versioned, AI-ready context — versioned documents, deterministic queries, integrity verification, and MCP integration for AI agents

Readme

@promptowl/contextnest-cli

Versioned, reviewed knowledge for your AI agents. Start solo, scale safely.

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

by PromptOwl | Website | Whitepaper | Specification | Discord

npm License: AGPL-3.0 SOC 2 Type 2

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, fewer tokens per session, a sharing path, and governed change history when you need it.

New in 2.1 — no command writes to your working directory without saying so: --dry-run on every write command, an action log of what changed, and confirmation prompts on the destructive ones. See File safety. The install also drops from 104 packages to 2.

New in 2.0 — ctx now runs on the engine's shared operation catalog, so the CLI, the MCP server and the PromptOwl cloud all execute the same code for the same action. New: ctx info, ctx publish --all, ctx vault describe, ctx history --diff, --limit on list and search. See Upgrading to 2.0.

Install

npm install -g @promptowl/contextnest-cli

Two packages, no nesting, and no install scripts — nothing of ours executes when you install. For a lean install without terminal colour:

npm install -g @promptowl/contextnest-cli --omit=optional

That leaves exactly one package, with every command, flag and output format unchanged. The rest of the code is compiled into the published bundle rather than resolved from npm, so the install is deterministic — and every bundled package is listed with its version and licence in DEPENDENCIES.md.

Quick Start

# First run: bare `ctx` walks you through setup
ctx

# Or pick the vault options on a web page, then create it here
ctx setup

# 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"

First run. The first time you run ctx with no arguments, in a terminal, with no vault anywhere, it offers to create a local vault (ctx init --starter developer, registered as main), sign in to a team server (ctx login https://nest.promptowl.ai --as promptowl), do both, or skip. It never prompts in CI or without a TTY, and never onboards an existing user. After that, bare ctx prints the command list and exits 0.

ctx setup opens https://nest.promptowl.ai/setup (CONTEXTNEST_SETUP_URL for another server; --no-open prints the URL instead), waits for your choices, then runs ctx init or ctx login with them. ctx init --starter <recipe> --tools <claude,cursor,windsurf,copilot,gemini|none> picks the agent config files without a prompt.

Available Starters

| Recipe | For | What You Get | |--------|-----|-------------| | developer | Engineering teams | Architecture, coding standards, onboarding | | personal | Individual knowledge base | 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 personal-knowledge 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 knowledge base 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

Vault

  • ctx info — Show a vault's instructions, configuration and contents (--nodes to list them, --json for the raw payload). This opens an existing vault; ctx init creates one
  • ctx vault list — List registered vaults (* marks the default)
  • ctx vault add <alias> [path] — Register a vault
  • ctx vault describe <alias> [description] — Set or clear a registry description; omit the text to remove it
  • ctx vault default <alias> / ctx vault remove <alias> / ctx vault which
  • ctx vault rename <old> <new> — Renames an alias, local or remote. If the alias was the default, the default moves with it.
  • ctx hints on|off — Turns ctx's one-line hints on or off. Set CONTEXTNEST_NO_HINTS=1 to silence them for a single run.

Hosted nests

  • ctx login <server> — Sign in once in the browser; the CLI mints its own API key and keeps it in your OS keyring (or the encrypted file store — never plaintext). --key-stdin saves an existing cnst_… key instead (hidden prompt on a terminal; a server without browser login falls back to it)
  • ctx login <server> [--as <alias>] [--set-default] — Signing in also registers the server as a vault: ctx vault list then shows every nest as <alias>/<nest> (marked [server]). The alias comes from the host (nest.promptowl.ai → promptowl) unless you pass --as; it never takes your default vault unless it is your first one. --no-register saves the key without registering the server. With --nest <id>, the alias points at that nest.
  • ctx login <alias> — Signs you in again for a registered alias. Auth errors print the exact ctx login … command to run, and at a terminal a rejected key offers to sign you in on the spot. If you logged in before 3.4 but never registered the server, a one-line hint shows the ctx vault add … command to run. Don't re-run ctx login in that case, because it mints a second key.
  • ctx vault add <alias> --url <server>/mcp — Register the server; with a saved login no --bearer-env is needed. Then ctx --vault <alias> query …
  • ctx push --server <server> --nest <id> — Uses the saved key when --key / CONTEXTNEST_API_KEY are absent
  • ctx login --list [server] — Show the servers and nests you're logged into (never prints keys)
  • ctx login <server> --nest <id> --key-stdin — Save a key for one nest only; it wins over the server-wide key for that nest. Hosted (https://nest.promptowl.ai), self-hosted and nest-scoped keys all live side by side, so you never log out to switch. A nest key also works through a server alias as --vault <alias>/<nest>, with or without a server-wide key
  • ctx login <server> --account <name> — Sign in to the same server as a second account (say, a client's). Point an alias at it with ctx vault add <alias> --url <server>/mcp --account <name> (or ctx login … --account <name> --as <alias>); --list and ctx logout --account <name> take it too
  • ctx logout <server|alias> [--nest <id>] [--account <name>] | --all — Forget a server's keys (with its nest-scoped keys), one nest's key, or everything; --all also resets an unreadable store. Revoke keys on the server in the web UI

Document Management

  • ctx add <path> — Create a new document (refuses a path that already holds one — use ctx update)
  • ctx add <path> --type skill — Create a skill node with trigger, inputs, and guard rails
  • ctx add <path> --body-file <file|-> / ctx update <path> --body-file <file|-> — Reads the body from a file or stdin, so newlines, quotes and $ need no shell escaping.
  • ctx read <path> — Reads and displays a document in the terminal. A bare id (ctx read my-node) finds a node at the root of an Obsidian (flat) vault as well as at nodes/my-node.
  • ctx read <path> --body — Prints the body alone, so you can edit it and pass it back through --body-file.
  • 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 skill <path> — Render a type: skill node for an agent harness (--harness claude-code|cursor|codex|raw)
  • ctx skill install <path> --write — Install a vault skill locally. Defaults to --mode loader (fetches the procedure at runtime, cannot drift); --mode full embeds an offline copy that will
  • ctx update <path> — Updates a document. It refuses to replace the body with an empty one unless you pass --force.
  • ctx update <path> --assignee <email> --due <YYYY-MM-DD> --priority <urgent|high|medium|low> --parent <id> — Remote (Community) nest only: set task fields; the nest checks the assignee is on its roster. "" or none clears a field
  • ctx list --assignee <email|none> --priority <p|none> --due-before <YYYY-MM-DD> — Remote nest only: filter tasks
  • ctx task log <path> --note "…" [--status working|done|blocked] [--claim] [--agent <name>] — Remote nest only: record what you did on a task. Attributed to you, your API key and the agent (--agent or $CONTEXTNEST_AGENT), and shown in the task's activity. --claim assigns it to you if it is unassigned
  • ctx delete <path> — Delete a document (recorded in ctx forget-log; --purge for no record). Names the documents that will be left linking to it, and still deletes it
  • ctx archive <path> [--reason <text>] — Archive a document: out of lists and retrieval, history kept (spec §1.13)
  • ctx unarchive <path> — Bring an archived document back in the status it left
  • ctx move <path> <folder> — Move a document to another folder with its history; its id changes
  • ctx forget <path> --reason <code> — Forget a document (spec §6.3): erase its content from history, keep the hashes so ctx verify still passes
  • ctx import pdf <file...> [--folder f] [--tags t] [--id id] [--title t] [--no-publish] — Import PDFs as type: pdf nodes: the extracted text becomes the body and the PDF is kept beside it, bound by SHA-256. --id on an existing pdf node adds a new version (the old PDF stays in history). Scanned PDFs import with an empty body and a warning (no OCR)
  • ctx publish <path> — Publish (bump version, create checkpoint)
  • ctx publish --all — Publish every unpublished document in one batch, with a live counter. Seals one checkpoint and regenerates the index once, instead of once per document
  • ctx validate [path] — Validate against the spec. Also lists every dangling reference ([[wikilink]], contextnest:// link, depends_on) with its document and line, as warnings that leave the exit code alone; --json adds a dangling array
  • ctx list — List documents (filter by --type, --status, --tag; cap with --limit)
  • ctx search <query> — Full-text search, best match first (documents matching every term, then partial matches, each by relevance score). Prints the top 10; --limit <n> to change, --limit 0 for all; --json carries each hit's score. When combining with selector filters in ctx query, put the search term first (contextnest://search/foo + type:document) to keep ranked order — only the leftmost operand's order survives an AND/OR
  • ctx search <query> --mode lexical|semantic|hybrid [--rerank] — Searches by stemmed keywords (the default), by embeddings, or by both fused together. Semantic and hybrid search need an index, which ctx embed builds from published documents (--rebuild starts over). See retrieval modes.

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 <selector> --include-drafts — Include drafts (default: published only)
  • 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 history <path> --diff — Include each version's unified diff from the one before
  • ctx reconstruct <path> <version> — Reconstruct a specific version. A version the history does not contain is now refused rather than answered with a neighbouring version's content
  • ctx verify — Verify all hash chains (reports a history.yaml it cannot read instead of skipping it; forgotten versions verify hash-only)
  • ctx forget-log [path] — The forget audit trail (never the forgotten content)

File Safety

No command writes to your working directory without telling you. Three global flags govern every write:

| Flag | Effect | |------|--------| | --dry-run | Runs the command against a throwaway copy of the vault, prints the exact files it would touch, and leaves your vault untouched | | -y, --yes | Skips confirmation prompts — the "prior explicit consent" for scripts and CI | | --force | Overwrites an existing file, repoints a taken vault alias, or allows a plaintext-HTTP push |

ctx add nodes/spec --title "Spec" --dry-run   # preview, writes nothing
ctx delete nodes/spec --yes                   # destructive, so it needs the flag
ctx read nodes/spec --html --out out.html     # refuses to clobber out.html without --force

Action log. Every write command ends with the list of files it created (+), modified (~) or deleted (-), computed by comparing the vault before and after — so it reflects what actually happened, not what was intended. The log goes to stderr, leaving --json output and redirected stdout clean.

--dry-run covers the vault registry too: ctx vault add|remove|default|describe run against a throwaway copy of ~/.contextnest/, so a preview fails on an alias collision or an unregistered alias exactly where the real command would, rather than promising something that can't happen.

Confirmation. On a terminal, write commands ask before proceeding. Destructive ones (delete, checkpoint rebuild, drift approve, vault remove, re-running init over an existing vault, overwriting an --out file, push) default to no. Without a TTY nothing blocks on stdin: additive commands take their own argv as consent, destructive ones refuse unless --yes or --force was passed.

Network egress. ctx push lists the documents leaving your machine and asks before sending them. Plaintext HTTP to a non-loopback host is refused — it would put both the documents and your API key on the wire in the clear. Prefer CONTEXTNEST_API_KEY over --key: command-line arguments are visible to other processes and land in shell history.

Confirmation gate. A nest can require a human to confirm a push in the web UI before it is applied. When it does, ctx push prints a Confirm in the UI: link and waits for the decision, exiting 0 once the push is applied and non-zero if it is rejected, expires, or the wait times out. Use --no-wait to submit and exit without waiting, or --timeout <sec> to bound the wait (it defaults to the server's window, else 15 minutes). Ungated nests apply immediately, exactly as before. A push that runs straight through lists any document it skipped (already exists — never overwritten) or failed, and exits non-zero if one failed. On such a nest, ctx add against the remote vault is held the same way: it prints the nest's message and exits 0, and the document does not exist until a reviewer confirms it.

Caller attribution

Three global flags record who is calling on every read and write (spec §9.4):

| Flag | Effect | |------|--------| | --agent <name> | Name of the calling agent (env: CONTEXTNEST_AGENT) | | --session <id> | Calling session id (env: CONTEXTNEST_SESSION_ID) | | --client <key=value> | Extra caller metadata, repeatable |

ctx add nodes/spec --title "Spec" --agent claude-code --session s-9f2
ctx history nodes/spec
#   v1 [keyframe] published
#     By: [email protected] at 2026-08-22T15:54:47.356Z
#     Client: claude-code (session s-9f2)

A write that publishes records the block on its version-history entry, so ctx history shows which agent produced each version — distinct from By:, which is the authoring identity. Reads carry it too; nothing is persisted for them locally, but a governed backend receives it.

The env vars are the reason this is practical for agents: a plugin that shells out to ctx exports them once for a session instead of threading flags through every call. A flag beats the env var per key, so --agent on one command overrides the ambient agent while keeping the ambient session.

Human author

--author <email> (env: CONTEXTNEST_AUTHOR) records the human a write is for as edited_by — the By: line in ctx history. It applies to every local write: add, update (which auto-publishes), publish, delete, archive, forget, imports and the rest. Commands that already take -a, --author (publish, forget, archive, the paper imports) read the same value, so the env var is their default too. With neither, edited_by stays [email protected]. The flag beats the env var.

--author and --agent answer different questions, so one version can carry both: the human who approved the write, and the agent that made it.

export [email protected] CONTEXTNEST_AGENT=claude-code
ctx update nodes/spec --body "…"
ctx history nodes/spec
#   v2 published
#     By: [email protected] at 2026-11-08T12:00:00.000Z
#     Client: claude-code

Remote (Community) nests ignore it: the server records the author from the API key.

Values from --client are recorded as strings — a shell argument is text, and coercing version=1.0 to 1 would quietly lose characters from an audit record. Attribution is a label, never an identity claim: nothing authenticates it, and it is never used to authorize.

Errors

Every failure prints as a single line — Error [CODE]: message for engine errors, a plain Error: message for everything else. No stack traces leak into normal output.

CONTEXTNEST_DEBUG=1 ctx verify   # full stack trace when you need to debug

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 — Regenerates context.yaml and INDEX.md from a full crawl, which picks up edits made outside ctx. The agent config files (CLAUDE.md, GEMINI.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md) are written by ctx init and refreshed on every document write.

Upgrading to 2.0

Your vault files are untouched — no migration to run. Behaviour that changes:

  • A brand-new document now starts at v1. ctx add used to write version: 1 into frontmatter and let publish bump it, so a new document's history began at v2 with no v1 keyframe. Publish owns version assignment; existing documents are unaffected.
  • ctx vault list shows a vault's description where it previously fell back to its name. Vaults whose .context/config.yaml carries a description now display it. Precedence: registry description → the vault's own config description → its name.
  • ctx reconstruct refuses a version that does not exist instead of returning the nearest keyframe's content as though it were the version asked for.
  • ctx update --tags replaces the tag set rather than merging into it. Pass the full set you want.
  • ctx list --type document and --status rejected now actually match. Both silently returned nothing before — --type compared against an optional field with no default, and rejected documents were dropped before the status filter ran. Tags match with or without a leading #, and case-insensitively.
  • ctx init --description reaches the vault's own config, not just its registry entry.

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. [[wikilinks]] in document bodies become reference edges when the vault is indexed (ctx index reports how many, and how many failed to resolve), so wiki-style vaults traverse the same as ones linked with contextnest:// URIs.

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:

Atoms: #tag  type:X  status:X  pack:id  nodes/<id>  sources/<id>   Operators: space or + = AND, | = OR, - = NOT, ( ) to group

nodes/<id> is a bare node id — ctx query "nodes/gtm/foo" selects that one node (the long form contextnest://nodes/gtm/foo still works); sources/<id> does the same for a source node. A bare word without the nodes/ prefix is an error, with a hint. tag:#x, transport:X and server:X are also accepted.

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 "nodes/gtm/foo"                 # One node by id
ctx query "sources/jira"                  # One source node by id
ctx query "#api + #v2"                    # Intersection (AND): both tags
ctx query "#api | #v2"                    # Union (OR): either tag
ctx query "#api - #deprecated"            # Difference (NOT)
ctx query "(#api | #v2) + status:published"  # Group, then AND

Cloud Packs

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

ctx query @promptowl/executive-ai-strategy

Recipes (ctx pull)

A recipe is a node in a remote nest (slug recipe-<id>) whose body holds one fenced block that opens with ```yaml recipe. It names the remote nodes to copy and where they land, the skills to bring in, the template files to write at the vault root, and the pack to generate. Because the recipe is a node, it is stewarded and versioned like everything it describes.

ctx pull <remote-alias> --recipe org-essentials --dry-run   # show the plan, write nothing
ctx pull <remote-alias> --recipe org-essentials             # pull
ctx pull <remote-alias> --recipe org-essentials --update    # take newer upstream versions
  • Every pulled document lands as a draft with derived_from: contextnest://<nest>/<id> and metadata.pulled_from recording the upstream version. Review it, then ctx publish.
  • A later pull skips what is current, reports newer upstream versions (applied only with --update), and never overwrites a document or file it did not pull, nor a pulled one you have since edited or published.
  • Skills land as type: skill. Install one with ctx skill install <path> --mode loader --write.
  • Pulls write into a local vault for now; use ctx push to send the result to a hosted nest.
id: org-essentials
includes:
  - from: nodes/org/spine/the-accountability-method   # remote node id
    to: nodes/methodologies/accountability-method      # local document id
    tags: [prime-document]                             # optional, added to the source's tags
skills:
  - from: nodes/org/skills/distill-capture             # lands at nodes/skills/<slug> unless `to` is set
files:
  - from: nodes/org/templates/stewards-example         # first ```yaml block in the node; `to` must be .yaml/.yml, outside nodes/, packs/ and dot-folders
    to: stewards.example.yaml
pack:
  id: org-essentials
  include: [nodes/methodologies/accountability-method]
  agent_instructions: Load these first.

Kinds (kind: in a recipe, ctx kind apply)

A recipe can also carry a kind: section: the server-side half of a package. A pull never sends it anywhere. It validates the section and writes it to nodes/kinds/<recipe-id>, a draft with the same lineage as every other pulled document (derived_from points at the recipe node), so the kind is reviewed, published and versioned like the documents it ships with. ctx kind apply is the separate, explicit step that sends it to a hosted nest.

id: seam                       # must be a plain name when the recipe carries a kind
includes: [...]
kind:
  plugins:                     # PUT /nests/:id/plugins/:name (FEATURE_PLUGINS)
    - name: github
      mode: summary            # raw | summary
      settings:                # plain values only; secret-looking keys or values are refused
        repos: [org/repo]
  edge_types:                  # POST /nests/:id/edge-types, upsert by name (FEATURE_WORKFLOW_PLANE)
    - name: escalates-when
      description: Escalate the source to the target when the condition holds.   # required by the server
      is_flow: true
      condition_schema: { params: [CAC], mode_default: structured }
  edges:                       # POST /nests/:id/edges (FEATURE_WORKFLOW_PLANE)
    - from: nodes/playbooks/triage   # node ids as they exist in the target nest
      to: nodes/agents/escalate
      type: escalates-when           # declared above, or a stock type: next, on-success, on-failure, depends-on, owned-by
      condition: { mode: structured, term: CAC, op: ">", value: 500 }   # or { mode: nl|open, text: "..." }
  schedules:                   # POST /nests/:id/schedules (FEATURE_WORKFLOW_PLANE); one per agent
    - agent: nodes/agents/escalate   # an agent or skill node
      every_minutes: 60              # 5 to 10080
  stewards:                    # POST /nests/:id/stewards
    - scope: document          # document | tag | nest
      target: nodes/playbooks/triage   # a document id, or a tag; none for nest
      role: reviewer           # editor | reviewer | viewer
      principal: "@seam-owner" # always a placeholder; the person is chosen at apply time
  runner:
    handlers: [llm-judge]      # runner handlers the kind expects; informational

Unknown fields anywhere in kind: are refused (a structured condition takes only term, op and value), as is any plugin setting or condition value that looks like a secret. Stock edge types are used as they are, never redeclared in edge_types. Secrets are set on the server, never in a recipe.

ctx kind apply seam --server https://nest.example.com --nest <id> --steward @[email protected]        # plan only
ctx kind apply seam --server https://nest.example.com --nest <id> --steward @[email protected] --yes  # send it
  • Dry run by default. Without --yes, only GETs are sent: they check the key and the nest, and find out which planes are on.
  • Published kinds only. --yes refuses a kind that is still a draft — review and ctx publish it first, or pass --allow-draft to apply an unreviewed one deliberately (stewards switch governance on). "Published" means published under the vault's normal rules; it implies a review only when the vault has its review gate on.
  • Re-runs are safe. Anything the server already has (a 409) is reported as exists; an edge whose edge type failed in the same run is skipped, not sent. --steward emails are lowercased.
  • Authentication works as it does for ctx push: --key, CONTEXTNEST_API_KEY, or the key saved by ctx login; https (or localhost) only, and redirects are refused.
  • A plane the server has switched off answers 404. Its entries are skipped with a warning that names the flag (FEATURE_WORKFLOW_PLANE, FEATURE_PLUGINS). A plugin the server has not loaded is skipped too.
  • Plugins are configured but never enabled. Enable one on the server once its secrets are connected.
  • A schedule that already exists for an agent is left as it is. An edge or steward that already exists (409) is reported as present.
  • Stewards whose placeholder is not mapped with --steward @placeholder=email are not applied. Assigning a steward turns governance on for the nest.
  • Server ids come from the title and folder that ctx push sent. Edges and schedules name node ids as they exist in the target nest, and the server rejects ids it does not have.

AI Agent Integration

ctx init writes config files so AI tools discover your vault, and every document write keeps them in step with the index:

| 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 — 47 tools over stdio (the canonical context_* operation set — read/create/update/publish/import documents, selector queries, version history, drift governance, integrity verification):

# 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 — 47 tools | @promptowl/contextnest-mcp-server | | Engine | Core library — parsing, storage, versioning, graph traversal | @promptowl/contextnest-engine | | PromptOwl cloud | Hosted packs, SSO, approvals, role-scoped publishing | promptowl.ai |

Links

License

AGPL-3.0 — See LICENSE for details.

Using this inside an organization that restricts or prohibits AGPL, or embedding it in a proprietary product? A commercial license from PromptOwl removes the AGPL obligations.