CLI Reference

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

Global flags

Accepted by every subcommand:

Flag	Description
`--log-level <LOG_LEVEL>`	Logging verbosity: `trace`, `debug`, `info`, `warn`, `error`. Overrides the config file value and `-v`. Defaults to `warn` so interactive output stays clean; pass `--log-level info` or `-v` to see internal `INFO` lines.
`-v`, `--verbose...`	Increase verbosity: `-v` = info, `-vv` = debug, `-vvv` = trace. Ignored when `--log-level` is given explicitly.
`-h`, `--help`	Print help.
`-V`, `--version`	Print version (top level).

Two flags recur on specific commands:

--ollama-host <URL> — on index, serve, answer, setup, doctor, ci. Overrides the Ollama daemon HTTP base URL for embedder, summarizer, and runtime probes. Equivalent to CANOPY_OLLAMA_HOST=<url>. Default http://localhost:11434; an explicit [embedding.ollama] host in the TOML config still takes precedence.
--no-network — on index, serve, doctor, update. Refuses to run if any cloud-backend configuration is detected — the compliance “nothing leaves the box” assertion (also CANOPY_NO_NETWORK=1). Violations exit with code 2.

Exit codes

0 — success; non-zero — failure.
2 — --no-network violations, and usage errors such as naming the same step in both setup --only and setup --skip.
canopy ci exits non-zero when P0 findings are present (see --fail-on-p0).

canopy index

Index a repository. Incremental by default; --full wipes and re-indexes from scratch. Builds the Tantivy full-text search index by default (--no-search for AST-only) and vector embeddings by default (--no-embeddings for keyword-only). Git commit history is auto-ingested whenever .git/ is present at the repo root.

canopy index [OPTIONS] [PATH]

Flag	Default	Description
`[PATH]`	`.`	Repository root. Defaults to the current directory, so `canopy index` alone indexes the repo you’re standing in.
`--full`	—	Full (from-scratch) index instead of incremental.
`--no-search`	—	Skip the Tantivy full-text index (AST-only). The full-text index powers `canopy answer`’s keyword, pattern, and semantic recipes; pass this only when you don’t need those recipes.
`--with-git`	—	Force git history ingestion. Without it, git is auto-ingested when `.git/` is present.
`--no-git`	—	Skip git ingestion even when `.git/` is present.
`--max-commits <N>`	`1000`	Maximum git commits to ingest. Applies to both `--with-git` and the auto-detect path.
`--no-embeddings`	—	Skip vector embeddings (keyword-only index). Embeddings power the semantic recipes and need a provider: the bundled local ONNX model (auto-fetched on first use when online) or Ollama. Embedding failure is always non-fatal.
`--with-summaries`	—	Build the Tier-A file-summary vector index after AST/search indexing. Requires the search index and chunk embeddings; re-enables embeddings even if `--no-embeddings` was given. Failure is non-fatal.
`--summary-backend <BACKEND>`	config or `heuristic`	Summary backend: `ollama` \| `openai-compat` \| `anthropic` \| `heuristic`.
`--summary-endpoint <URL>`	—	HTTP base URL for the openai-compat backend.
`--summary-model <MODEL>`	—	Provider-specific model identifier for the summary backend.
`--summary-api-key-env <ENV_VAR>`	`CANOPY_SUMMARY_API_KEY`	Environment variable holding the summary backend’s API key.
`--summary-auth-style <STYLE>`	—	Auth header style for openai-compat: `bearer` \| `api-key`.
`--summary-concurrency <N>`	`4`	Maximum concurrent summary requests during indexing.
`--rebuild-summaries`	—	Force-regenerate every summary regardless of cached `content_hash`. Use after changing the summary backend or model.
`--allow-mixed-backends`	—	Override the summary-backend fingerprint check and proceed when the active backend differs from the one that built the existing rows. Not recommended for production indexes — KNN scores against mixed rows are noisy.
`--cache-to [<URI>]`	—	Push the built index to the CI cache after indexing. Bare `--cache-to` uses `[cache]` config + an auto-derived key (BYOB); `r2://<team>/<key>` is the legacy GST-managed form. The auto-derived key composes repo git SHA + canopy version + config hash + summaries state. Team tier. Push failures are non-fatal.
`--cache-to-allow-dirty`	—	Allow `--cache-to` from a dirty working tree. By default the push refuses when `git status --porcelain` is non-empty — a dirty tree means HEAD SHA understates the indexed content.
`--use-cache [<URI>]`	—	Fetch the index from the CI cache before indexing; a hit skips the rebuild entirely. Same two URI forms as `--cache-to`. Team tier. Miss or fetch failure falls through to normal indexing.
`--no-default-ignore`	—	Skip the bundled default ignore set. Use only when you genuinely want build artifacts indexed. `.gitignore` + `.canopyignore` are still honored.
`--no-gitignore`	—	Skip `.gitignore`, `.git/info/exclude`, `.ignore`, and global gitignore honoring.
`--no-canopyignore`	—	Skip `.canopyignore` honoring (repo-root file, gitignore syntax).
`--ignore-pattern <GLOB>`	—	Extra exclude globs (repeatable), matched against the full path; use `**/` for any-depth. Composes with defaults + `.gitignore` + `.canopyignore`. Malformed patterns are skipped with a warning.
`--list-ignored`	—	Diagnostic: print what would be indexed vs skipped (grouped by top-level directory), then exit without indexing.

Also accepts --ollama-host and --no-network.

canopy index                 # incremental index of the current repo
canopy index /my/repo --full # full re-index

canopy serve

Start the canopy MCP stdio server for a repository. The server exposes tools over JSON-RPC 2.0 on stdin/stdout. With --watch, changed files are re-indexed automatically. The tool surface is always the single canopy_answer tool — see the canopy_answer Reference.

canopy serve [OPTIONS] [PATH]

Flag	Default	Description
`[PATH]`	current directory	Repository root.
`--watch`	—	Background file watching and incremental re-indexing.
`--dashboard`	—	Start the local web dashboard alongside the MCP server (Solo tier or higher). In community mode an upgrade message is printed and the MCP server starts without the dashboard.
`--answer`	—	Answer-engine convenience: implies `--watch` and bootstraps the full-text search index in the background if missing, so every answer recipe works. No Ollama required — keyword search is independent of the optional embedding tier.
`--print-mcp-config`	—	Print the exact MCP wiring snippet for this repo and exit (does not start the server). The snippet reflects the resolved repo path and any flags you passed. Works in every tier.
`--client <CLIENT>`	`claude`	Config format for `--print-mcp-config`: `claude` (`.mcp.json` block + `claude mcp add` one-liner), `cursor` (`~/.cursor/mcp.json` block), `zed` (`settings.json` `context_servers` block).

Also accepts --ollama-host and --no-network.

canopy answer

One-call natural-language answer over the indexed repo — the human-CLI counterpart to the canopy_answer MCP tool. Routes the question to a deterministic internal recipe and prints one answer. The repo is auto-detected from the current working directory; pass an optional [PATH] to override. Phrasing picks the recipe: name the entity type and backtick paths/symbols (see question shapes).

canopy answer [OPTIONS] <QUESTION> [PATH]

Flag	Default	Description
`<QUESTION>`	—	The natural-language question. Keep backticks around file paths, directories, and symbol names (e.g. `src/lib.rs`, `MyStruct`) so the classifier can locate them.
`[PATH]`	current directory	Optional repository path, to answer against a different indexed repo.
`--format <FORMAT>`	recipe default	Output density: `concise` or `standard` (fuller answer with citations). Omit to let each recipe pick its own density.

Also accepts --ollama-host.

canopy answer "where is the function \`dispatch_tool\` defined?"
canopy answer "what depends on \`src/lib.rs\`?" --format standard
canopy answer "architecture overview" ~/code/other-repo

canopy ingest

Ingest external data into the repo index.

canopy ingest [OPTIONS] <COMMAND>

Subcommand	Description
`scip`	Ingest a SCIP index file for compiler-precise code intelligence.
`coverage`	Ingest test coverage data (LCOV, Istanbul JSON, or Cobertura XML).

Git history is not ingested here — canopy index auto-ingests it when .git/ is present.

canopy setup

Set up the embedding runtime — downloads and configures Ollama and the embedding model automatically; supports offline installation from a bundle (--bundle-path). Run once before indexing (canopy index builds embeddings by default). Safe to re-run — skips steps that are already done. Steps: license → embedding → summary → cache → mcp (wires every detected MCP editor) → index.

canopy setup [OPTIONS]

Flag	Default	Description
`--bundle-path <PATH>`	—	Path to the offline embedding bundle GST ships — the `.tar.gz` tarball or a pre-extracted directory. Installs offline instead of downloading. (Replaces the former `canopy model bundle install`.)
`--yes`	—	Non-interactive mode. Per-step defaults: license → Community Mode; embedding → install Ollama + nomic-embed-text; summary → heuristic; cache → skip; mcp → wire every detected editor silently; index → run on cwd if it’s a git repo.
`--only <STEP>`	—	Only run the named step(s). Repeatable. Valid: `license`, `embedding`, `summary`, `cache`, `mcp`, `index`. Naming the same step in both `--only` and `--skip` is a usage error (exit code 2).
`--skip <STEP>`	—	Skip the named step(s). Repeatable. Same valid names.

Also accepts --ollama-host.

canopy activate

Activate a Canopy license key or team invite token. Key activation validates the Ed25519-signed key offline (no network call), writes the parsed license data to ~/.canopy/license.json, and prints the tier, features, and expiration date. Team invite activation exchanges an invite token with the admin portal API for a full license — team members never see a raw key.

canopy activate [OPTIONS] [KEY]

Flag	Default	Description
`[KEY]`	—	The license key from your purchase email. Mutually exclusive with `--team`.
`--team <TOKEN>`	—	Activate with a team invite token from your team admin instead of a license key.

canopy license

Show the current license status: tier, email (masked), features, and expiry date when a valid license is installed; a community-mode feature summary otherwise. No command-specific flags.

canopy license

canopy doctor

Pre-flight diagnostic: install info, active backend, data-flow row, and credential-env-var presence. A one-stop “what would canopy do right now?” view — run it before opening a support ticket, before legal review, and before flipping --no-network. The data-flow row mirrors the data-sovereignty documentation so audit copies can paste it verbatim.

canopy doctor [OPTIONS]

Flag	Default	Description
`--repo <REPO>`	`.`	Repository path. The repo’s `[summaries.<repo>]` config (or `[summaries_default]` fallback) determines the “would-activate” backend the report describes.
`--json`	—	Output raw JSON instead of the human-readable report.

Also accepts --ollama-host and --no-network.

canopy update

Check for or install binary updates. Fetches the latest release manifest from https://downloads.canopy.gulfshieldtech.com. With --check, only prints the available version and download URL; without it, downloads and replaces the running binary in-place after a SHA-256 integrity check.

canopy update [OPTIONS]

Flag	Default	Description
`--check`	—	Only check for updates — do not download or install.

Also accepts --no-network.

canopy plugins

Manage first-party plugin packs (React / Rust / Python / Supabase). Packs are bundled YAML health-check sets embedded in the binary. install copies a pack into <repo>/.canopy/plugins/, where the health runtime picks it up automatically on the next canopy index or canopy ci run.

canopy plugins [OPTIONS] <COMMAND>

Subcommand	Description
`list`	List bundled packs + which ones are installed in this repo.
`install`	Install a bundled pack into `<repo>/.canopy/plugins/<pack>.yaml`.
`disable`	Remove an installed pack from `<repo>/.canopy/plugins/`.

canopy ci

Run Canopy in CI mode: index, health check, output annotations in GitHub Actions / GitLab / Azure Pipelines / SARIF formats, exit non-zero if P0 findings are present. Requires a Pro tier license (or higher). Use --team with a Team tier license to enable automatic R2 index caching, which skips the index rebuild when the repo SHA has not changed.

canopy ci [OPTIONS]

Flag	Default	Description
`--repo <REPO>`	`.`	Repository path.
`--format <FORMAT>`	`auto`	Output format: `github`, `gitlab`, `sarif`, `json`, or `auto` (detect from CI env). `sarif` emits SARIF 2.1.0 suitable for GitHub Code Scanning upload.
`--changed-only`	—	Restrict findings to files changed in the current PR, computed from `git diff --name-only $BASE...HEAD` (BASE = `origin/$GITHUB_BASE_REF` in GitHub Actions, falling back to `origin/main`). No effect outside a git repo or when the base cannot be resolved.
`--fail-on-p0`	—	Fail the build if any P0 finding is present.
`--team <TEAM>`	—	Team ID for automatic CI cache usage (Team tier). Computes the R2 cache URI from team ID + repo path, then passes `--use-cache` and `--cache-to` to the index step.
`--no-cache`	—	Skip downloading the R2 cache even if `--team` is set. Forces a full rebuild; the result is still uploaded after the build.
`--clear-cache`	—	Delete the cached index from R2 before running, then rebuild and re-upload. Requires `--team`. Implies `--no-cache` for the download step.
`--with-summaries`	—	Build the Tier-A summary index too. With `--team`, the cache slot is partitioned by summary backend and model so summaries-on and summaries-off runs never cross-contaminate.

Also accepts --ollama-host.

canopy completions

Generate a shell completion script. Prints to stdout by default; pass --install to write it to the shell’s standard completion directory automatically.

canopy completions [OPTIONS] <SHELL>

Argument	Description
`<SHELL>`	Target shell: `bash`, `elvish`, `fish`, `powershell`, or `zsh`.

Flag	Description
`--install`	Write the script to the shell’s standard location (bash / zsh / fish) and print where it landed plus how to activate it. No standard drop-in directory exists for `powershell` / `elvish` — those still print to stdout.

Install automatically (recommended):

canopy completions bash --install   # → ~/.local/share/bash-completion/completions/canopy
canopy completions zsh  --install   # → ~/.local/share/zsh/site-functions/_canopy (or $ZSH/completions under Oh My Zsh)
canopy completions fish --install   # → ~/.config/fish/completions/canopy.fish

--install honors XDG_DATA_HOME / XDG_CONFIG_HOME. Or redirect it yourself:

canopy completions bash > /etc/bash_completion.d/canopy

canopy deactivate

Removes this machine’s fingerprint from the license binding list. Use when replacing a laptop or decommissioning a machine. After deactivation, the freed seat can be used by running canopy activate on another machine.

canopy deactivate [OPTIONS]

Flag	Default	Description
`--yes`	—	Confirm without interactive prompting.

canopy config

Manage the license heartbeat and transparency settings.

canopy config [OPTIONS] <COMMAND>

Subcommand	Description
`get`	Print the effective value of a config field plus its provenance.
`set`	Set a config field. TOML-AST aware — preserves comments and other sections. Default target `~/.canopy/config.toml`; pass `--repo` to write to `<repo>/.canopy/config.toml`.
`list`	Dump the effective config (or one section) to stdout, preserving source comments.
`edit`	Open the target config file in `$EDITOR` (default `vi`). Validates TOML on save; restores a timestamped `.bak.<utc-epoch>` backup if the save is unparseable.
`reset`	Remove a field from a config file. Precedence falls through to the next layer down (per-repo → user-global → compiled default).
`heartbeat`	Manage the weekly license heartbeat.
`team`	Show team configuration loaded from `.canopy/team.yml`.

canopy cache

Verify the CI index cache backend. Set one up with canopy setup --only cache.

canopy cache [OPTIONS] <COMMAND>

Subcommand	Description
`verify`	Validate the configured cache backend without running an index. For `backend = "s3"`: constructs the backend (resolves env vars) and issues a HEAD probe against a synthetic key — proves auth + bucket access. For `gst-managed`: reports pending-Worker status. For `none`: prints a hint to run `canopy setup --only cache`.

canopy repo

Manage the canopy multi-repo registry. Register, remove, and inspect all repositories tracked by canopy; each registered repo gets its own index database in ~/.canopy/indexes/. Requires a Pro tier license.

canopy repo [OPTIONS] <COMMAND>

Subcommand	Description
`add`	Register a repository with canopy.
`remove`	Remove a repository from the canopy registry.
`list`	List all registered repositories with their last-indexed time.
`status`	Show index freshness and file counts for all registered repositories.

canopy dashboard

Start (or open) the local web dashboard. If canopy serve --dashboard is already running, this just opens the browser at the dashboard URL; otherwise it starts a standalone dashboard server and opens the browser. Requires a Solo tier license (or higher); the --repos multi-repo override additionally requires Pro.

canopy dashboard [OPTIONS]

Flag	Default	Description
`--repo <REPO>`	current directory	Repository path.
`--port <PORT>`	`4040`	Port to bind the dashboard server to.
`--no-open`	—	Start the server without opening the browser.
`--repos <REPOS>...`	—	Multi-repo override: comma-separated repository paths forming a transient registry (Pro tier). Overrides `~/.canopy/repos.json` for this invocation only; the first entry is the default repo.

canopy attributions

Display or export third-party software attribution notices. Canopy includes dozens of permissively-licensed open-source components.

canopy attributions [OPTIONS]

Flag	Default	Description
`--html`	—	Write the full `LICENSES.html` attribution document to disk (default `./LICENSES.html`).
`--text`	—	Print condensed text attribution (license names and crate counts).
`--output <OUTPUT>`	`./LICENSES.html`	Output path for `--html` mode.

canopy attributions                # summary to stdout
canopy attributions --text         # condensed attribution text
canopy attributions --html         # write LICENSES.html to the current directory

Deprecated & hidden

These exist for compatibility but are hidden from canopy --help. Do not build on them.

Command	Status
`trial` / `upgrade`	Hidden. `canopy license` prints the trial and pricing URLs.
`cache init`	Hidden. Use `canopy setup --only cache`.
`ingest git`	Hidden. `canopy index` auto-ingests git history when `.git/` is present (`--with-git` / `--no-git` / `--max-commits` control it).
`model`	Producer builds only. Customers use `canopy setup --only embedding` and `canopy setup --bundle-path`.
`licenses`	Replaced by `canopy attributions`.