Copass CLI

The Copass CLI (copass) is the fastest way to get data out of your developer environment and into your Copass vault. It runs in any terminal, authenticates with your Copass account, and gives you a single command surface for ingestion, retrieval, and project setup. Under the hood it targets the same public API documented under API Reference — you’re just skipping the work of wiring up tokens, session encryption, and sandbox management yourself.

Install

npm install -g @copass/cli

Requires Node.js 20+. Verify the install:

copass --version

Authenticate

copass login

This kicks off an email-based OTP flow. On success, your access + refresh tokens are written to ~/.olane/config.json along with an auto-generated master encryption key. The CLI uses that key to derive a per-request session token — the server never sees your master key and cannot decrypt your data without it.

Back up ~/.olane/config.json or set COPASS_ENCRYPTION_KEY in your environment before running copass login on a new machine. If you lose the master key, encrypted vault objects can’t be recovered.

First-run setup in a project

Run setup once in any project directory to bootstrap it against Copass:

cd ~/your/project
copass setup

setup will, in order:

Confirm you’re authenticated (and prompt for a Copass ID handle if you haven’t claimed one).
Drop a .olane/ directory at the project root with templates + config.
Create a sandbox in your Copass account (the top-level tenancy unit).
Register a filesystem data source for this directory.
Create a storage project inside the sandbox and link the data source.
Persist all three ids to .olane/refs.json.
Offer to install a continuous-indexing watch service (launchd on macOS, systemd on Linux).

From this point on every command run from this directory targets that sandbox + project automatically.

Ingest data into your vault

The primary day-to-day command. Send anything — text, code, markdown, JSON — and Copass chunks it, extracts entities, and stores it in your sandbox vault.

From stdin

echo "The auth service uses Supabase OTP for session tokens." | copass ingest

From a file

copass ingest src/auth.ts
copass ingest docs/architecture.md
copass ingest data/customers.json

The source_type is auto-derived from the file extension (code / markdown / json / text). Override it for semantic hints:

# flag the payload as an architecture decision
echo "Migrating the ingest pipeline to SQS for backpressure" | copass ingest --source-type decision

# a correction you want the graph to prioritize
echo "The old README said X; the correct behavior is Y" | copass ingest --source-type correction

# user-shared context
cat user-note.txt | copass ingest --source-type user_input

Common --source-type values: code, markdown, json, text, conversation, decision, correction, user_input, documentation.

Useful flags

Flag	Purpose
`--stdin`	Explicitly read from stdin (useful when scripting).
`--source-type <type>`	Override the auto-derived source_type.
`--file-path <path>`	Display path used for source_type inference when piping.
`--project-id <id>`	Scope to a specific storage project (defaults to the one pinned in `.olane/refs.json`).
`--storage-only`	Chunk + store in the vault without running ontology extraction.
`--json`	Emit a single JSON document for scripting.

Example output

$ copass ingest src/auth.ts --json
{
  "job_id":        "f95ddf5b-…",
  "status":        "queued",
  "sandbox_id":    "bf7adb5a-…",
  "project_id":    "9f44edce-…",
  "status_url":    "/api/v1/storage/sandboxes/bf7adb5a-…/ingest/f95ddf5b-…",
  "encrypted":     true
}

Every ingest returns an async job id. The server vault-writes the raw bytes first, then queues a background chunking + extraction job; you can poll status_url to follow progress, or — more commonly — just keep ingesting.

Index a whole project at once

copass index --mode full

Scans the project tree (honoring .gitignore), pushes every file through your data source, and reports a summary. Useful for bootstrapping a fresh project. For ongoing changes:

copass index --mode incremental

Only re-ingests files whose content hashes changed since the last index. Preview without pushing anything:

copass index --mode full --dry-run
copass index --mode incremental --dry-run

Keep the vault fresh (watch mode)

Foreground watcher:

copass watch

Install as a background service (recommended for active repos):

copass watch install-service
copass watch status
copass watch uninstall-service

The watcher debounces filesystem events and pushes changes through the same data source as copass ingest. State (file fingerprints, last-sync timestamps) is kept in .olane/watch-state.json.

Retrieve from your vault

Five retrieval commands — three form the progressive disclosure gradient (discover → interpret → search), plus entities for disambiguation and question for one-shot NL answers. Use the gradient for agent-driven, window-aware retrieval; use question or entities for one-off terminal queries.

Progressive retrieval: `discover` → `interpret` → `search`

copass discover "how does the auth service handle token refresh?"

Returns a menu of relevant context paths (e.g. Auth Service > Tokens > refresh policy) with scores and a canonical_ids tuple per item. Cheap, structural, no prose. The first step of any exploratory retrieval flow. Flags:

--project-id <uuid> — narrow scope
--history-turns <n> — recent Claude Code transcript turns to fold in (default 20)
--reference-date YYYY-MM-DD
--json — machine-readable output

`copass interpret` — pinned brief

copass interpret '[["abc-123"],["def-456","ghi-789"]]' \
  --message "why is checkout flaky this week?"

Pass the canonical_ids tuple(s) from one or more discover items as a JSON array. Returns a 1-2 paragraph brief grounded in the source content behind those items. Flags:

--message <text> — the user’s current question (used to frame the brief)
--project-id <uuid>
--history-turns <n>
--json

`copass search` — synthesized answer

copass search "how does the auth service handle token refresh?" --preset auto

Full synthesized natural-language answer. Heaviest of the three calls — use when the question is self-contained and you don’t need to stage through discover. Flags:

--preset fast|auto|max — retrieval mode (default fast). fast for sub-second; auto for higher-quality synthesis; max is reserved and coming soon
--detail-level concise|detailed
--max-tokens 4000
--project-id <uuid>
--reference-date YYYY-MM-DD
--history-turns <n>
--json

Look up canonical entities: `copass entities`

copass entities "BaseDataSource"

Returns the canonical entities in your sandbox that best match the query, ranked by semantic similarity. Lightweight — great for disambiguation or confirming a specific entity exists. For broader context, reach for discover instead.

Ask a natural-language question: `copass question`

copass question "how does the auth service handle token refresh?"

Single-shot natural-language question against the knowledge graph. Same surface shape as copass search — pick whichever reads better in your terminal. Flags: identical to copass search.

Check project status

copass status

Reports:

Whether the project is linked (refs.json present).
Data source status + last sync time.
Watch service state.
Encryption-key source (env var vs. global config).
Next-step recommendations when something is missing.

Use --json to pipe into scripts or other tools.

Point the CLI at a non-default backend

Three ways, in precedence order:

# 1. Environment variable (highest priority)
export COPASS_API_URL=https://your-instance.copass.id

# 2. Per-project override in .olane/config.json
#    (set with `copass config project set defaults.api_url=https://…`)

# 3. Global override in ~/.olane/config.json
copass config set api_url https://staging.copass.id

Default: https://api.copass.id.

Expose the CLI to LLM agents

copass mcp starts a Model Context Protocol server over stdio that wraps every ingestion and retrieval verb as an LLM-callable tool. See MCP Server for the tool list and Claude Code / Cursor integration snippets.

Scripting with `--json`

Every ingestion and retrieval command accepts --json and emits a single JSON document on stdout:

# Ingest the current PR body
gh pr view --json body -q .body | copass ingest --source-type user_input --json | jq -r .job_id

# Count incremental changes
copass index --mode incremental --dry-run --json | jq '.upserts | length'

# Pipe entity hits into fzf
copass entities "auth" --json | jq -r '.entities[].name' | fzf

Command reference

Command	Purpose
`copass login` / `copass logout`	Authenticate / sign out
`copass setup`	Bootstrap the current project (sandbox + data source + project)
`copass ingest [file]`	Ingest content from a file or stdin
`copass index --mode full\|incremental [--dry-run]`	Index the project tree
`copass watch [install-service\|status\|uninstall-service]`	Continuous indexing
`copass discover <message>`	Ranked menu of related context paths (progressive disclosure step 1)
`copass interpret <items-json>`	1-2 paragraph brief pinned to chosen canonical tuples (step 2)
`copass search <query>`	Synthesized natural-language answer (step 3)
`copass entities <query>`	Canonical-entity vector similarity lookup
`copass question <question>`	Single-shot natural-language question
`copass status`	Project + watch + auth status
`copass config set\|get\|list`	Global config CRUD
`copass config project list\|get\|set\|validate`	Per-project config CRUD
`copass transcript clean <file>`	Parse Claude Code transcript JSONL
`copass mcp`	Start the MCP stdio server
`copass upgrade`	Self-update the CLI

Run copass <cmd> --help for the full option surface on any command.

File layout on disk

~/.olane/config.json              global auth + master key
<project>/.olane/config.json      per-project config (human-editable)
<project>/.olane/refs.json        sandbox_id / data_source_id / project_id
<project>/.olane/watch-state.json file fingerprints for incremental runs

Reset a project locally — next copass ingest will re-bootstrap fresh ids:

rm <project>/.olane/refs.json

Next steps

SDK — framework adapters, MCP server, and the create-copass-agent scaffold for embedding Copass in your own app.
API Reference — the raw HTTP endpoints, if you’d rather integrate directly.
Security — how Copass handles encryption, sandbox isolation, and data retention.

Getting Started

Copass Context

Agent Router

Collaboration

Developer Tools

Cookbooks

Security

Install

Authenticate

First-run setup in a project

Ingest data into your vault

From stdin

From a file

Useful flags

Example output

Index a whole project at once

Keep the vault fresh (watch mode)

Retrieve from your vault

Progressive retrieval: `discover` → `interpret` → `search`

`copass discover` — ranked menu

`copass interpret` — pinned brief

`copass search` — synthesized answer

Look up canonical entities: `copass entities`

Ask a natural-language question: `copass question`

Check project status

Point the CLI at a non-default backend

Expose the CLI to LLM agents

Scripting with `--json`

Command reference

File layout on disk

Next steps

Getting Started

Copass Context

Agent Router

Collaboration

Developer Tools

Cookbooks

Security

​Install

​Authenticate

​First-run setup in a project

​Ingest data into your vault

​From stdin

​From a file

​Useful flags

​Example output

​Index a whole project at once

​Keep the vault fresh (watch mode)

​Retrieve from your vault

​Progressive retrieval: discover → interpret → search

​copass discover — ranked menu

​copass interpret — pinned brief

​copass search — synthesized answer

​Look up canonical entities: copass entities

​Ask a natural-language question: copass question

​Check project status

​Point the CLI at a non-default backend

​Expose the CLI to LLM agents

​Scripting with --json

​Command reference

​File layout on disk

​Next steps

Install

Authenticate

First-run setup in a project

Ingest data into your vault

From stdin

From a file

Useful flags

Example output

Index a whole project at once

Keep the vault fresh (watch mode)

Retrieve from your vault

Progressive retrieval: `discover` → `interpret` → `search`

`copass discover` — ranked menu

`copass interpret` — pinned brief

`copass search` — synthesized answer

Look up canonical entities: `copass entities`

Ask a natural-language question: `copass question`

Check project status

Point the CLI at a non-default backend

Expose the CLI to LLM agents

Scripting with `--json`

Command reference

File layout on disk

Next steps