contextvault-cli

The Context Vault CLI — login, file operations, agent registration, and local file tracking.

Install

npm install -g contextvault-cli

Binary: cv. Node ≥ 20 required.

Quickstart

Run cv with no arguments to open the interactive menu — arrow keys to navigate, no subcommand syntax to memorize:

$ cv

────────────────────────────────────────────────────────────────
  ██████╗   ██████╗ ███╗   ██╗████████╗███████╗██╗  ██╗████████╗
 ██╔════╝  ██╔═══██╗████╗  ██║╚══██╔══╝██╔════╝╚██╗██╔╝╚══██╔══╝
 ██║       ██║   ██║██╔██╗ ██║   ██║   █████╗   ╚███╔╝    ██║
 ██║       ██║   ██║██║╚██╗██║   ██║   ██╔══╝   ██╔██╗    ██║
 ╚██████╗  ╚██████╔╝██║ ╚████║   ██║   ███████╗██╔╝ ██╗   ██║
  ╚═════╝   ╚═════╝ ╚═╝  ╚═══╝   ╚═╝   ╚══════╝╚═╝  ╚═╝   ╚═╝
          ██╗   ██╗ █████╗ ██╗   ██╗██╗  ████████╗
          ╚████╔╝   ██║  ██║ ╚████╔╝╚████████║
            ╚═╝     ╚═╝  ╚═╝  ╚═══╝  ╚══════╝
────────────────────────────────────────────────────────────────
  the context platform for the agent-native enterprise
  cli v0.1.0

  Active workspace: Helios Robotics  (ws-mngwr1n8-uhqfgq)

? What would you like to do?
❯ Browse vault            (cv ls)
  Read artifact           (cv cat)
  Push a file             (cv push)
  Push a folder           (cv push-folder)
  Watch a folder          (cv watch)
  Register an agent       (cv agent register)
  …

For scripting and power-users, every menu item is also available as a subcommand:

# Authorize this device against a workspace. Opens a browser flow.
cv login

# Verify your token and see which workspace you're in.
cv whoami

# List the catalog (workspace → departments).
cv ls

# Drill into a department or folder.
cv ls engineering
cv ls engineering/architecture

# Read an artifact's contents.
cv cat engineering/architecture/auth-design-doc

# Upload a single file.
cv push ./README.md engineering/docs/

# Recursive upload (one-shot).
cv push-folder ./my-docs --to engineering/imports

# Live sync — every change to a local directory mirrors into the vault.
cv watch ./my-docs --to engineering/local

Switching workspaces

The CLI stores credentials per-workspace at ~/.contextvault/credentials.json.

cv workspaces            # list workspaces this CLI has credentials for
cv use ws-abc123         # set the active workspace
cv logout                # remove the active workspace's credentials
cv logout --all          # remove everything

To add a new workspace, run cv login while signed into that workspace's account.

Registering an agent

Agents authenticate with API tokens (the cv_* format). The CLI mints them in one step and writes the raw token to ~/.contextvault/agents/<actor_id>.token.

# Read-only agent that watches engineering/
cv agent register weekly-digest \
  --type operator \
  --grants 'r:engineering/**'

# Read+write across the whole workspace
cv agent register importer \
  --type agent \
  --grants 'r:**,w:engineering/**'

# Inspect what's registered
cv agent list

Use the saved token from your agent process:

TOKEN=$(cat ~/.contextvault/agents/weekly-digest.token)
curl http://localhost:3010/api/cv/catalog \
  -H "Authorization: Bearer $TOKEN"

Live file tracking

cv watch follows a local directory and pushes changes as new artifact versions. Useful for keeping draft documents in sync with the vault while you edit them locally.

cv watch ./design-docs --to engineering/architecture

• Pushes are concurrency-4.
• State persists at ~/.contextvault/watch/<workspace>/<hash>.state.json so restarts skip unchanged files.
• Hidden files and common build dirs (node_modules, .git, .next, dist, etc.) are skipped.
• Use --once to do a single pass and exit.
• Use --dry-run to log what would be pushed without uploading.

Configuration

| Env var | Default | Description | |---|---|---| | CONTEXTVAULT_API_BASE | http://localhost:3010 | Override the API base URL (e.g. https://contextvault.metisos.co). |

Files

| Path | Purpose | |---|---| | ~/.contextvault/credentials.json | Per-workspace bearer tokens. Chmod 600. | | ~/.contextvault/agents/*.token | Agent API tokens, one per actor_id. | | ~/.contextvault/watch/{org}/{hash}.state.json | Per-watch state (last-pushed mtimes). |

Using the CLI from an agent

Shell-running agents (Claude Code, Codex, Devin, custom orchestrators) can use the same CLI. We publish a portable agent skill that documents the commands, auth flow, error handling, and idiomatic patterns:

• Skill URL: https://contextvault.metisos.co/skills/contextvault-cli.md
• In-repo: skills/contextvault-cli/SKILL.md

Have your agent fetch it once at session start and prepend it to its system prompt, or drop it into ~/.claude/skills/ for Claude Code to discover automatically. The user mints a scoped token with cv agent register; the agent reads the skill and starts working.

License

Apache-2.0