@copass/cli

Olane 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 (recommended)

npm install -g @olane/o-cli

Homebrew

brew tap olane-labs/tap
brew install olane

From source

git clone https://github.com/olane-labs/o-cli.git
cd o-cli
pnpm install
pnpm build

Requires Node.js >= 20.0.0.

Quick start

# Authenticate
olane login

# Initialize your project
olane setup

# Index your codebase
olane index --mode full

# Start continuous incremental indexing in the foreground
olane watch

# Query the knowledge graph
olane copass question "How does authentication work in this project?"

# Search for entities
olane search "UserService"

Commands

Authentication

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

Project

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

Copass (Knowledge Graph)

Command	Description
olane copass question <question>	Natural language Q&A against your ontology
olane copass context <canonical-id>	Get LLM-generated context summary for an entity
olane copass score <query>	Score knowledge graph coverage for an entity name, UUID, or free text

Search & Ingestion

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

Configuration

Command	Description
olane config set <key> <value>	Set a config value
olane config get <key>	Get a config value
olane 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 olane copass context <canonical-id> to get an LLM-generated summary of an entity's context.

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 olane login.

Project config (.olane/config.json)

Stores project-specific settings including cosync thresholds, indexing schedules, and hook configuration. Created by olane 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.

Install on an operator workstation

git clone https://github.com/olane-labs/o-cli.git
cd o-cli
pnpm install
pnpm run build:admin
pnpm link --global        # exposes `copass-admin` on your PATH

copass-admin includes the full public command surface plus operator-only admin commands.

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.