@copass/cli

Copass CLI

Command-line interface for the Olane Network — interact with the Copass knowledge graph, ingest code and documentation, and query your project's ontology.

Installation

npm install -g @copass/cli

Requires Node.js >= 20.0.0.

Quick start

# Authenticate
copass login

# Initialize your project
copass setup

# Index your codebase
copass index --mode full

# Start continuous incremental indexing in the foreground
copass watch

# Surface relevant context (ranked menu)
copass discover "How does authentication work in this project?"

# Get a synthesized natural-language answer
copass search "How does authentication work in this project?"

Commands

Authentication

Command	Description
copass login	Sign in with email (OTP verification)
copass logout	Clear stored auth tokens

Project

Command	Description
copass setup	Interactive project initialization
copass status	Check indexing status and project health
copass index --mode <full|incremental>	Index project for ontology enrichment
copass watch	Watch the project for continuous incremental indexing
copass watch status	Check watch service health and last sync
copass watch install-service	Install and start the background watch service
copass watch uninstall-service	Remove the background watch service

Knowledge Graph

Command	Description
copass discover <message>	Ranked menu of context items relevant to a message
copass search <query>	Synthesized natural-language answer grounded in the knowledge graph
copass question <question>	Legacy alias for search (still functional)
copass interpret <items>	Legacy — LLM brief pinned to canonical_ids. Prefer search for drill-in.

Search & Ingestion

Command	Description
copass search <query>	Search ontology by name or description
copass ingest code [file]	Ingest source code for entity extraction
copass ingest text [file]	Ingest text or documentation

Configuration

Command	Description
copass config set <key> <value>	Set a config value
copass config get <key>	Get a config value
copass config list	List all config values

MCP Server

copass mcp

Starts a Model Context Protocol server over stdio, exposing the Copass tool surface (retrieval + management) to MCP-aware agents.

MCP integration

Add Copass as an MCP server in your .mcp.json:

{
  "mcpServers": {
    "copass": {
      "type": "stdio",
      "command": "copass",
      "args": ["mcp"]
    }
  }
}

Available MCP tools

The MCP surface is the canonical @copass/mcp tool set (retrieval + Context Window + ingest + management) plus a thin layer of CLI-LOCAL and deprecated-but-functional passthroughs from this CLI. See the @copass/mcp README for the harness tool reference; the CLI-side additions are listed in the migration notes below.

Migration from 2.x to 3.0

@copass/cli 3.0.0 retires the in-tree MCP server and delegates to the canonical harness server (@copass/mcp). The set of MCP tools available to your agent changes as follows.

Renamed tools

• show_source → get_source
• show_agent → get_agent
• list_agent_runs → list_runs

Update your agent's tool allowlist; the old names are no longer registered.

Removed tools

• entities — use discover + search
• question — use search
• update_agent — use one of:
  • update_agent_prompt (system prompt only)
  • update_agent_tools (tool allowlist only)
  • update_agent_tool_sources (tool source allowlist only)
• index_project — run copass index from the CLI; not exposed via MCP
• show_sandbox — use list_sandboxes filtered by id

The three replaced tools (entities, question, update_agent) remain registered as stderr-warning stubs in 3.0.x and are removed entirely in 3.1.0.

Deprecated-but-functional (will move into @copass/mcp v0.4)

The following tools continue to work via CLI-shellout passthroughs but emit a [deprecated; will move to harness in v0.4] description prefix. They migrate into the harness spec corpus in a future release.

• Sandbox lifecycle: create_sandbox, rename_sandbox, suspend_sandbox, reactivate_sandbox
• Source lifecycle: register_source, rename_source, pause_source, resume_source
• Trigger lifecycle: show_trigger
• Agent: test_agent

The following previously-shellout tools are now first-class harness tools (no longer CLI-shellout passthroughs): test_user_mcp_source, revoke_user_mcp_source, create_trigger, update_trigger.

Authentication

The MCP server now reuses the local CLI auth — running copass login is sufficient. COPASS_API_KEY and COPASS_SANDBOX_ID env vars remain supported as explicit overrides; .olane/refs.json (written by copass setup) is honored when no env override is set, and a single sandbox is auto-selected when the user owns exactly one.

Copass scoring

Cosync scores measure confidence in the knowledge graph's understanding of entities:

Tier	Meaning
safe	High confidence, well-understood entity
review	Moderate confidence, may benefit from verification
caution	Low confidence, likely needs enrichment
critical	Very low confidence, significant gaps
cold_start	New entity with minimal data

Use copass search "<question about the entity>" for a synthesized answer grounded in that entity's region of the graph. (copass interpret <canonical-id> is the legacy path — still works but prefer search.)

Supported languages

Code ingestion supports: TypeScript, JavaScript, Python, Rust, Go, Java, Ruby, PHP, C, C++, C#, Swift, Kotlin, Scala, Bash, SQL, YAML, JSON, Markdown, HTML, CSS, SCSS, Vue, and Svelte.

Configuration

Global config (~/.olane/config.json)

Stores authentication tokens, API endpoints, and encryption keys. Created automatically on copass login.

Project config (.olane/config.json)

Stores project-specific settings including cosync thresholds, indexing schedules, and hook configuration. Created by copass setup. Continuous indexing settings are stored under the watch section, and successful full indexes refresh .olane/watch-state.json so background watching can resume without re-uploading unchanged files.

Environment variables

Variable	Description
OLANE_API_URL	API endpoint (default: https://ai.copass.id)
OLANE_ENCRYPTION_KEY	Master encryption key
OLANE_PROJECT_ID	Default project ID

Security

All data in transit is encrypted using AES-256-GCM. Each project can have its own master encryption key, stored locally or provided via environment variable. Session tokens wrap a derived encryption key with your access token for secure API communication.

License

MIT

Internal / Admin Build

This section is for Copass operators only. If you installed the CLI from npm, this does not apply to you.

An internal admin build of this CLI exists as a separate binary (copass-admin). It is not published to npm and cannot be installed via npm install -g. The admin surface is excluded from the public bundle at build time (separate tsconfig, separate outDir, package.json "files" whitelist, plus a prepublishOnly safety check). There is no runtime flag to "unlock" admin commands in the public binary — the code simply isn't there.

Environment variables

Variable	Purpose
COPASS_ADMIN_API_TOKEN	Required. Operator credential — admin commands refuse to run without it.
COPASS_ADMIN_API_URL	Optional. Admin API base URL. Defaults to https://ai.copass.id.

Contributor guide

See src/commands/admin/README.md for the contributor walkthrough: adding new admin commands, operator auth seam, conventions, and what not to do.

Never publish admin artifacts

See RELEASING.md. The publish pipeline refuses to run with admin artifacts present — do not disable the check.