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.