CLI Reference

Canopy ships as a single binary: canopy. All subcommands follow the form canopy <subcommand> [flags].

A global --log-level flag (values: trace, debug, info, warn, error) is accepted by every subcommand and overrides the config file value. The default is info.

Exit codes: 0 for success, 1 for any error (the error message is printed to stderr).

canopy index

Index a repository. Performs an incremental index by default; use --full to wipe and re-index from scratch.

canopy index <path> [flags]

Flag	Type	Default	Description
`path`	string (positional)	—	Path to the repository root. Required.
`--full`	bool	false	Wipe the existing index and re-index from scratch.
`--with-search`	bool	false	Build the Tantivy full-text search index after AST indexing. Required before `canopy search` and `canopy_search` work.
`--with-git`	bool	false	Ingest git commit history after AST indexing. Equivalent to running `canopy ingest-git` afterward.
`--max-commits`	integer	1000	Maximum git commits to ingest when `--with-git` is set.
`--with-embeddings`	bool	false	Generate vector embeddings for semantic search. Requires `--with-search`. Embedding failure is non-fatal. (Requires `embeddings` build feature.)
`--cache-to`	string	—	Push the built index to R2 team cache. Format: `r2://<team_id>/<cache-key>`. Requires Team tier.
`--use-cache`	string	—	Fetch index from R2 team cache before indexing; skips rebuild on hit. Format: `r2://<team_id>/<cache-key>`. Requires Team tier.

Examples:

# Incremental index with search support
canopy index . --with-search

# Full re-index including git history
canopy index /my/repo --full --with-search --with-git

# CI: use cached index if available, push new cache after
canopy index . --use-cache r2://team_abc123/main --cache-to r2://team_abc123/main

Expected output:

Indexed 622 files in 2.6s (incremental)
Search index built: 622 chunks

canopy serve

Start the Canopy MCP stdio server. Exposes all tools over JSON-RPC 2.0 on stdin/stdout.

canopy serve [path] [flags]

Flag	Type	Default	Description
`path`	string (positional)	current directory	Path to the repository root.
`--watch`	bool	false	Enable background file watching; triggers incremental re-index on file save.
`--dashboard`	bool	false	Start the local web dashboard alongside the MCP server. Requires Solo tier or higher.

Examples:

canopy serve .
canopy serve /my/repo --watch

canopy status

Show current index statistics for a repository.

canopy status [flags]

Flag	Type	Default	Description
`--repo`	string	current directory	Path to the repository.

Expected output:

Repository: /my/repo
Files indexed: 622
Last indexed: 2026-04-16 10:30 UTC
Stale files: 0
Git history: available (1000 commits)
License: Solo — p***[email protected] (expires 2027-04-15)

canopy health

Run health checks and print findings grouped by severity.

canopy health [flags]

Flag	Type	Default	Description
`--repo`	string	current directory	Path to the repository.
`--no-secret-scan`	bool	false	Disable the secret-scanning health check.

Exit codes: 0 for no findings or warnings/info only; 1 for any P0 (critical) or P1 (error) findings.

Expected output:

P0 Critical: 0
P1 Error:    1
  [ERROR] broken_imports: src/api/handler.ts imports '../models/user' which does not exist
P2 Warning:  3
P3 Info:     5

canopy map

Generate an architecture map for a repository.

canopy map [flags]

Flag	Type	Default	Description
`--repo`	string	current directory	Path to the repository.
`--output`	string	stdout	Output file path.

Example:

canopy map --repo . --output terrain/ironpine-labs/architecture.md

canopy search

Full-text search across indexed code chunks. Understands camelCase and snake_case: searching payment finds processPayment, payment_handler, and PaymentService.

Requires the search index (run canopy index --with-search first).

canopy search <query> [flags]

Flag	Type	Default	Description
`query`	string (positional)	—	Keywords. Supports AND/OR and quoted phrases.
`--repo`	string	current directory	Path to the repository.
`--language`	string	—	Restrict to a language: `typescript`, `rust`, `python`, `go`.
`--chunk-type`	string	—	Restrict to a chunk type: `function`, `class`, `interface`, `module_header`.
`--limit`	integer	10	Maximum results to return.

Example:

canopy search "payment handler" --language typescript --limit 5

canopy pattern

Structural AST pattern search using $VAR wildcards for single-node matches and $$$VAR for multi-node spreads.

canopy pattern <pattern> [flags]

Flag	Type	Default	Description
`pattern`	string (positional)	—	Code pattern to search for.
`--repo`	string	current directory	Path to the repository.
`--language`	string	—	Restrict to a language.
`--limit`	integer	20	Maximum results to return.

Examples:

canopy pattern 'console.log($$$ARGS)'
canopy pattern 'async function $NAME($$$PARAMS) { $$$BODY }'
canopy pattern 'fn $NAME($$$) -> Result<$$$, $$$> { $$$BODY }' --language rust

canopy ingest-scip

Ingest a SCIP index file. Upgrades heuristic import edges to compiler-resolved edges. Requires Pro tier or higher.

canopy ingest-scip <path> [flags]

Flag	Type	Default	Description
`path`	string (positional)	—	Path to the SCIP index file (typically `index.scip`).
`--repo`	string	directory containing the SCIP file	Repository root path.

canopy ingest-coverage

Ingest test coverage data. Auto-detects LCOV, Istanbul JSON, or Cobertura XML.

canopy ingest-coverage <path> [flags]

Flag	Type	Default	Description
`path`	string (positional)	—	Path to the coverage file.
`--repo`	string	current directory	Repository root, used to resolve relative file paths in the report.

canopy ingest-git

Ingest git commit history. Populates the commits and file_changes tables; enables canopy_git_history, canopy_git_blame, and hotspot analysis.

canopy ingest-git [flags]

Flag	Type	Default	Description
`--repo`	string	current directory	Path to the repository.
`--max-commits`	integer	1000	Maximum commits to ingest.

canopy git-blame

Show git blame for a file, grouped by commit section.

canopy git-blame <file> [flags]

Flag	Type	Default	Description
`file`	string (positional)	—	File path (relative to the repository root or absolute).
`--repo`	string	current directory	Repository path.

canopy warmup-model

Pre-download the embedding model without running inference. Run once before canopy index --with-embeddings to avoid blocking on a download. (Requires embeddings build feature.)

canopy warmup-model [flags]

Flag	Type	Default	Description
`--model`	string	`nomic-embed-text-v1.5`	Model name to download and verify.

canopy setup

Set up the embedding runtime. Downloads and configures Ollama and the embedding model automatically. Safe to re-run. (Requires embeddings build feature.)

canopy setup [flags]

Flag	Type	Default	Description
`--bundle-path`	string	—	Path to an offline bundle directory. When provided, installs from the bundle instead of downloading from the internet.

canopy bundle

Create or install an offline embedding bundle for air-gapped installations. (Requires embeddings build feature.)

canopy bundle create

canopy bundle create [flags]

Flag	Type	Default	Description
`--output`	string	`forge-embedding-bundle.tar.gz`	Output path for the bundle tarball.

canopy bundle install

canopy bundle install <path>

Argument	Type	Description
`path`	string (positional)	Path to a bundle tarball produced by `canopy bundle create`.

canopy activate

Activate a Canopy license key or team invite token. License key validation is performed entirely offline (Ed25519 signature check); no network call is made. Team invite activation exchanges the token with the admin portal API.

canopy activate [<key>] [flags]

Flag	Type	Default	Description
`key`	string (positional)	—	License key from your purchase email. Mutually exclusive with `--team`.
`--team`	string	—	Team invite token provided by your team admin.

Example:

canopy activate eyJrZXkiOi....<signature>
canopy activate --team invite_abc123

Expected output:

License activated.
  Tier:     Solo
  Email:    p***[email protected]
  Features: dashboard, workflow_tools
  Expires:  2027-04-15

canopy license

Show the current license status, masked email, features, and expiry date.

canopy license

No flags. Shows community-mode feature summary if no license is installed.

canopy update

Check for or install binary updates from https://downloads.canopy.ironpinelabs.com.

canopy update [flags]

Flag	Type	Default	Description
`--check`	bool	false	Only print the available version and URL; do not download.

canopy stats

Show local usage statistics from ~/.canopy/stats.json. Data never leaves the machine.

canopy stats [flags]

Flag	Type	Default	Description
`--json`	bool	false	Output raw JSON instead of a human-readable table.
`--reset`	bool	false	Reset all statistics (prompts for confirmation).

canopy ci

Run Canopy in CI mode: index, health check, output annotations in CI platform formats, exit non-zero on P0 findings. Requires Pro tier or higher.

canopy ci [flags]

Flag	Type	Default	Description
`--repo`	string	`.`	Repository path.
`--format`	string	`auto`	Output format: `github`, `gitlab`, `azure`, or `auto` (detects from CI environment variables).
`--fail-on-p0`	bool	false	Exit with code 1 if any P0 finding is present.
`--team`	string	—	Team ID for automatic R2 index cache usage. Requires Team tier.

canopy upgrade

Open the pricing and trial page in the default browser. On headless systems (no DISPLAY or WAYLAND_DISPLAY), prints the URL to stdout instead.

canopy upgrade

No flags.

canopy deactivate

Remove this machine’s license association. Use when replacing a laptop or decommissioning a development machine.

canopy deactivate [flags]

Flag	Type	Default	Description
`--yes`	bool	false	Confirm deactivation without an interactive prompt.

canopy config heartbeat show

Display the heartbeat status, last check time, cached result, and the exact payload transmitted. Nothing is sent by running this command.

canopy config heartbeat show

canopy config heartbeat now

Force an immediate heartbeat, bypassing the weekly schedule. Use after re-subscribing or to test connectivity. Exits non-zero if the heartbeat fails.

canopy config heartbeat now

canopy licenses

Display or export third-party software attribution notices.

canopy licenses [flags]

Flag	Type	Default	Description
`--html`	bool	false	Write the full `LICENSES.html` attribution document to disk.
`--text`	bool	false	Print condensed text attribution (license names and crate counts).
`--output`	string	`./LICENSES.html`	Output path for `--html` mode.

Examples:

canopy licenses                         # Print summary to stdout
canopy licenses --text                  # Condensed attribution text
canopy licenses --html                  # Write LICENSES.html to current directory
canopy licenses --html --output /tmp/   # Write to a specific path