@mediamonks/canopy-cli 0.7.12 → 0.7.14

package/dist/docs/cli-index.md

@@ -0,0 +1,61 @@
+---
+title: Installing the CLI
+description: Install the canopy CLI, sign in, and learn the conventions every command shares.
+---
+
+Everything on Canopy is driven by one command-line tool: `canopy`. It scaffolds projects, runs them locally, deploys them, and manages their data — this section is the reference for every command.
+
+## Install
+
+The CLI is published on npm as `@mediamonks/canopy-cli`. You need Node.js 20 or newer; then install it globally:
+
+```bash
+npm install -g @mediamonks/canopy-cli
+```
+
+Confirm it's on your PATH:
+
+```bash
+canopy --version
+```
+
+## Sign in
+
+Canopy authenticates through Monks' OneLogin. Run [`canopy login`](https://docs.canopy.website/cli/login) — it opens your browser, waits for the redirect back, and stores tokens in `~/.canopy/config.json`. Verify with [`canopy whoami`](https://docs.canopy.website/cli/whoami), which prints who you're signed in as on each site.
+
+## Staying up to date
+
+[`canopy upgrade`](https://docs.canopy.website/cli/upgrade) reinstalls the latest release using whichever package manager installed the CLI. You rarely need to remember it: once a day the CLI checks the npm registry in the background (never blocking your command), and when you're behind it prints a one-line hint on stderr — `Update available: x.y.z → a.b.c. Run 'canopy upgrade' to update.` The check is silent in CI and when output is piped, and can be disabled with `CANOPY_NO_UPDATE_CHECK=1`.
+
+## Conventions every command follows
+
+**Sites and `--profile`.** Canopy runs as several independent sites (`main`, `staging`, `gcp-pilot`). Every command accepts a global `--profile <site>` flag — or the `CANOPY_PROFILE` environment variable — to pick which site it talks to. Without either, the site comes from the `profile` pin in the project's `canopy.json`, then from the active default chosen at login. See [Sites & profiles](https://docs.canopy.website/platform/sites-and-profiles).
+
+**The site header.** Every command starts by printing one line to stderr, e.g. `canopy 0.5.1 · main (canopy.website)` — so the command log always shows which version ran against which site. It goes to stderr on purpose: stdout stays clean for piping.
+
+**`--json`.** [`canopy login`](https://docs.canopy.website/cli/login) and [`canopy usage`](https://docs.canopy.website/cli/usage) take a `--json` flag that prints machine-readable JSON to stdout instead of the human-formatted view — handy for agents and scripts. Other read commands keep stdout clean and stable for piping.
+
+**`--help`.** `canopy <command> --help` prints the authoritative usage and flags for any command straight from the installed version, so it never goes stale.
+
+## Commands
+
+- [canopy login](https://docs.canopy.website/cli/login) — sign in through OneLogin in your browser
+- [canopy whoami](https://docs.canopy.website/cli/whoami) — show who you're signed in as, per site
+- [canopy logout](https://docs.canopy.website/cli/logout) — clear stored tokens
+- [canopy create](https://docs.canopy.website/cli/create) — scaffold and register a new project
+- [canopy init](https://docs.canopy.website/cli/init) — set up a folder for an existing project
+- [canopy projects](https://docs.canopy.website/cli/projects) — list your projects
+- [canopy delete](https://docs.canopy.website/cli/delete) — delete a project and its data
+- [canopy dev](https://docs.canopy.website/cli/dev) — run a project locally
+- [canopy deploy](https://docs.canopy.website/cli/deploy) — build and deploy a new version
+- [canopy rollback](https://docs.canopy.website/cli/rollback) — make a previous version live again
+- [canopy download](https://docs.canopy.website/cli/download) — download a deployed version's files
+- [canopy token](https://docs.canopy.website/cli/token) — manage deploy tokens for CI
+- [canopy db](https://docs.canopy.website/cli/db) — pull, snapshot, and restore project data
+- [canopy usage](https://docs.canopy.website/cli/usage) — AI spend and storage for a project
+- [canopy open](https://docs.canopy.website/cli/open) — open the live project in your browser
+- [canopy docs](https://docs.canopy.website/cli/docs) — read the Canopy guides, offline-capable
+- [canopy skill](https://docs.canopy.website/cli/skill) — install the Canopy agent skill into a repo
+- [canopy upgrade](https://docs.canopy.website/cli/upgrade) — update the CLI itself
+
+`canopy logs` (tail a project's worker logs) exists as a stub for a planned feature and currently exits with a pointer to the roadmap.

package/dist/docs/cli-init.md

@@ -0,0 +1,46 @@
+---
+title: canopy init
+description: Set up a local folder for a project that already exists on Canopy — scaffold a starter or link an existing app.
+---
+
+`canopy init` connects a local directory to a project that **already exists** on Canopy — one created in the dashboard, or by `canopy create` on another machine. Where `create` registers a new project, `init` never registers anything: it only prepares files locally.
+
+## Usage
+
+```bash
+canopy init                                # pick a project, scaffold ./<slug>/
+canopy init retro-board . --no-scaffold    # link the current dir to an existing project
+canopy init retro-board apps/board --template spa
+```
+
+## Arguments & flags
+
+- `<slug>` — the project's slug. When omitted on a TTY you pick from the projects you can edit. The slug must exist and you must have edit access, or the command errors.
+- `<dir>` — target directory: `.` for the current directory, any path, or `./<slug>/` when omitted.
+- `--template <id>` — starter to scaffold: `static` (plain HTML/CSS/JS, no build), `spa` (Vite + React + TypeScript), or `worker` (`spa` plus a backend worker). Picker when omitted on a TTY, `static` otherwise.
+- `--no-scaffold` — link mode: skip the template and only write a `canopy.json` pointing the directory at the project. Use this for an app you've already built. (`--scaffold` is the default.)
+- `--profile <site>` — global flag (or `CANOPY_PROFILE`): which site to resolve the project on; the profile is pinned into the written `canopy.json`.
+
+## How it works
+
+The CLI first fetches your project list and validates the slug against it — a wrong slug or missing edit access fails before any files are written.
+
+**Scaffold mode** (default) requires the target directory to be empty-ish (missing, or holding only dotfiles like `.git`). It copies the chosen template in, then writes `canopy.json` with the slug and profile pin — the same result as `canopy create`, minus the registration. If the directory has files, the error tells you to use `--no-scaffold` instead.
+
+**Link mode** (`--no-scaffold`) writes just a `canopy.json` with the slug (creating the directory if needed). If a `canopy.json` already links the directory to a _different_ project, the command refuses rather than silently relinking; if it already links to the same project, it's a no-op. After linking, add `"dist"` or `"build"` fields to `canopy.json` if your app has a build step, then `canopy deploy`.
+
+## Examples
+
+```bash
+canopy init
+```
+
+Lists the projects you can edit, scaffolds your pick into `./<slug>/`, and prints next steps.
+
+```bash
+canopy init landing-page . --no-scaffold
+```
+
+Writes a `canopy.json` in the current directory linking it to `landing-page`, so `canopy deploy` knows where to publish.
+
+To register a brand-new project instead, see [canopy create](https://docs.canopy.website/cli/create). See also [canopy projects](https://docs.canopy.website/cli/projects).

package/dist/docs/cli-login.md

@@ -0,0 +1,43 @@
+---
+title: canopy login
+description: Sign in to Canopy through OneLogin in your browser and store CLI tokens for every site.
+---
+
+`canopy login` signs you in through your browser with OneLogin and stores CLI tokens locally. It's the first command you run on a new machine, and the one you come back to when `canopy whoami` says your token expired.
+
+## Usage
+
+```bash
+canopy login
+canopy login --profile main        # non-interactive: pick the default site up front
+canopy login --json                # machine-readable status for agents/CI
+```
+
+## Arguments & flags
+
+- `--profile <site>` — which site (`main` | `staging` | `gcp-pilot`) becomes your active default after login. On an interactive terminal you get a picker when omitted; on a non-TTY (or with `--json`) the flag — or the `CANOPY_PROFILE` env var — is required.
+- `--json` — emit machine-readable JSON status lines to stdout instead of interactive output. First a `{"status": "waiting", "url": …}` line with the sign-in URL, then `{"status": "ok", …}` or `{"status": "error", …}` (exit code 1 on error).
+
+## How it works
+
+1. The CLI opens your default browser on the OneLogin sign-in page. If nothing opens, it prints the URL for you to visit manually.
+2. You finish signing in **in the browser** — your password never passes through the CLI. When OneLogin hands control back, the browser shows a small "You're signed in" page and you can return to the terminal. The sign-in waits up to 5 minutes; the hand-back uses local port `8976`, so if another program holds that port the login fails with a clear message.
+3. The CLI stores a token for **every** site (`main`, `staging`, `gcp-pilot`), not just the one you picked, in `~/.canopy/config.json` — readable only by your user account.
+
+One login therefore covers all sites; `--profile` only decides which one commands target by default. If minting fails for a non-active site you get a warning but login still succeeds; if it fails for your **active** profile the command errors and asks you to re-run.
+
+## Examples
+
+```bash
+canopy login
+```
+
+Opens OneLogin, prompts you to pick a default site, and finishes with a per-site checklist plus your email — you're ready for `canopy create` or `canopy deploy`.
+
+```bash
+CANOPY_PROFILE=staging canopy login --json
+```
+
+Headless-friendly: prints the sign-in URL as JSON so an agent can hand it to you, then reports per-profile results when the browser flow completes.
+
+See also [canopy whoami](https://docs.canopy.website/cli/whoami), [canopy logout](https://docs.canopy.website/cli/logout), and [Sites & profiles](https://docs.canopy.website/platform/sites-and-profiles).

package/dist/docs/cli-logout.md

@@ -0,0 +1,32 @@
+---
+title: canopy logout
+description: Sign out of Canopy by removing all locally stored CLI tokens.
+---
+
+`canopy logout` signs you out on this machine by forgetting every stored CLI token. Use it on a shared machine, or when you want a clean slate before logging in as someone else.
+
+## Usage
+
+```bash
+canopy logout
+```
+
+## Arguments & flags
+
+None. Logout is deliberately all-or-nothing: it clears the tokens for **every** site (`main`, `staging`, `gcp-pilot`) at once — there is no per-profile logout, so the global `--profile` flag has no effect here.
+
+## Details
+
+The command is local-only: it removes every stored token from `~/.canopy/config.json` and prints a confirmation. Nothing is called on the server, so the tokens themselves aren't revoked — they simply age out at their normal expiry. Your active-site choice stays in the file, so the next `canopy login` picks up where you left off.
+
+If no token was stored to begin with, it prints `Not logged in.` and exits successfully.
+
+## Examples
+
+```bash
+canopy logout
+```
+
+Removes all site tokens from `~/.canopy/config.json`; subsequent commands that need the API will ask you to run `canopy login`.
+
+See also [canopy login](https://docs.canopy.website/cli/login) and [canopy whoami](https://docs.canopy.website/cli/whoami).

package/dist/docs/cli-logs.md

@@ -0,0 +1,57 @@
+---
+title: canopy logs
+description: Read your project worker's logs (console output) from the terminal — no cloud console access needed.
+---
+
+`canopy logs` prints what your project's worker wrote to `console.log` / `console.error`. Reach for it when the worker misbehaves — a 500, an unexpected 403, a schedule that "did nothing" — instead of adding diagnostic endpoints and redeploying. The same output lives in the dashboard under the project's **Logs** tab.
+
+Logs are available on every site that runs workers. On a site where the platform can't read worker output, the command says so honestly instead of guessing. One caveat on Cloudflare-hosted sites: log capture starts with a project's next deploy after 2026-08-19 — a worker that hasn't been redeployed since then has nothing to show yet.
+
+## Usage
+
+```bash
+canopy logs [--project <slug>] [--staging] [--since 1h] [--limit 100] [--follow] [--json]
+```
+
+## Arguments & flags
+
+- `--project <slug>` — project slug. Defaults to the `canopy.json` in the current directory.
+- `--staging` — read the staging channel's worker instead of live. Default `false`.
+- `--since <when>` — how far back to read: a duration like `30s`, `15m`, `2h`, `1d`, or a timestamp. Default `1h`.
+- `--limit <n>` — max entries to print, 1–1000. Default `100`.
+- `--follow` / `-f` — keep polling for new entries every few seconds until you Ctrl-C.
+- `--json` — print entries as JSON lines (`{ ts, severity, text }`) instead of formatted text.
+
+## How it works
+
+Every request your worker handles captures its stdout/stderr; `canopy logs` reads that capture through the platform (project members only — there's no direct cloud access to grant or leak). Entries print oldest-first as:
+
+```
+SEVERITY  timestamp  text
+```
+
+`console.error` output is tagged `ERROR` and `console.warn` is `WARNING`; `console.log` stays `DEFAULT`. Text is verbatim — whatever the worker logged, including multi-line JSON. Thrown errors show up too: an uncaught exception in a request handler becomes one `ERROR` entry with the full stack trace (and the request answers a 500), so a crashing endpoint is diagnosable from the log alone.
+
+It's read-only and stdout-clean: entries go to stdout for piping, everything else to stderr.
+
+## Examples
+
+```bash
+canopy logs --since 15m
+```
+
+The last quarter hour of worker output for the project in the current directory.
+
+```bash
+canopy logs -f
+```
+
+Watch logs live while you exercise the app — the closest thing to a terminal attached to your deployed worker.
+
+```bash
+canopy logs --staging --since 1d --json | jq -r 'select(.severity == "ERROR") | .text'
+```
+
+Just yesterday's errors from the staging worker, for a script or an agent.
+
+See also [Troubleshooting](https://docs.canopy.website/guides/troubleshooting) for what to do with what you find, and [canopy staging](https://docs.canopy.website/cli/staging) for the staging channel.

package/dist/docs/cli-open.md

@@ -0,0 +1,41 @@
+---
+title: canopy open
+description: Open the deployed project in your browser.
+---
+
+`canopy open` opens the project's live URL in your default browser — the quickest way to look at what's actually deployed, typically right after a `canopy deploy`.
+
+## Usage
+
+```bash
+canopy open [dir] [--project <slug>]
+```
+
+## Arguments & flags
+
+- `--staging` — open the [staging channel](https://docs.canopy.website/guides/staging) (`staging-dot-<slug>`) instead of the live site.
+
+- `[dir]` — project directory to read `canopy.json` from. Defaults to the current directory.
+- `--project <slug>` — project slug, overriding `canopy.json`.
+
+## How it works
+
+The command resolves the project slug, builds the live URL from the active site's project domain (projects are served at `https://<slug>.<site domain>`), prints the URL, and opens it in your default browser. Which domain that is depends on the active profile — `--profile staging` opens the project on the staging site, not production.
+
+It does not deploy, check, or wait for anything: if the project has never been deployed, the browser simply lands on whatever the platform serves for an empty project. To open the dashboard instead, use the URL printed by [canopy projects](https://docs.canopy.website/cli/projects).
+
+## Examples
+
+```bash
+canopy deploy && canopy open
+```
+
+Ship and eyeball: deploys the current directory's project, then opens the freshly-live site.
+
+```bash
+canopy open --project my-app --profile staging
+```
+
+Opens `my-app` as served by the staging site, regardless of what the current directory pins.
+
+See also [canopy deploy](https://docs.canopy.website/cli/deploy) and [Sites & profiles](https://docs.canopy.website/platform/sites-and-profiles).

package/dist/docs/cli-projects.md

@@ -0,0 +1,43 @@
+---
+title: canopy projects
+description: List your Canopy projects with their status, role, and live URLs.
+---
+
+`canopy projects` lists the projects you can work on for the current site — one line each with slug, status, your role, live URL, and name. It's the quickest way to recall a slug, check what you have access to, or confirm you're on the site you think you are.
+
+## Usage
+
+```bash
+canopy projects
+canopy projects --all
+canopy --profile staging projects
+```
+
+## Arguments & flags
+
+- `--all` — include projects you can't edit. By default the list shows only projects where you're an owner or editor (admins always see everything, since they can edit everything).
+- `--profile <site>` — global flag (or `CANOPY_PROFILE`): each site has its own project registry, so listing on `staging` shows a completely different set than `main`.
+
+## Details
+
+The command fetches your project list from the platform and prints one aligned row per project: slug, status, your role (`owner` / `editor`; for `--all` rows you can't edit it shows the owner's email instead, and admins see `admin`), the live URL, and the display name.
+
+With nothing to show, the message distinguishes the two cases: no projects exist at all (`run canopy create`), or none are yours — in which case it mentions how many `--all` would reveal.
+
+The CLI version and active site are printed on stderr, keeping stdout clean for piping — handy since the output is stable, column-aligned text.
+
+## Examples
+
+```bash
+canopy projects
+```
+
+Shows your own projects on your default site, e.g. to grab a slug for `canopy init` or `canopy delete`.
+
+```bash
+canopy projects --all
+```
+
+Shows every project on the site, with owner emails for the ones you can't edit — useful for finding who to ask for access.
+
+See also [canopy create](https://docs.canopy.website/cli/create), [canopy init](https://docs.canopy.website/cli/init), and [Members & access](https://docs.canopy.website/platform/members-and-access).

package/dist/docs/cli-promote.md

@@ -0,0 +1,44 @@
+---
+title: canopy promote
+description: Make the staged version live — migrations replay against the live database first, then the exact staged artifacts go live.
+---
+
+`canopy promote` takes what you verified on the [staging channel](https://docs.canopy.website/guides/staging)
+and makes it live. It is not a redeploy: the platform re-uses the exact files
+and backend bundle of the staged version, so what you tested is what ships.
+
+## Usage
+
+```bash
+canopy promote                  # promote the currently staged version
+canopy promote v8               # promote a specific version
+canopy promote --yes            # skip the confirmation (CI)
+```
+
+## Arguments & flags
+
+- `[version]` — the version to make live, as `8` or `v8`. Defaults to whatever
+  is currently staged; errors when nothing is staged and no version is given.
+- `--project <slug>` — project slug, overriding `canopy.json`.
+- `--dir <path>` — project directory (defaults to the current directory).
+- `--yes` — skip the confirmation prompt.
+- `--profile <site>` / `CANOPY_PROFILE` — which site to promote on.
+
+## What happens, in order
+
+1. **Migrations replay against live.** Any schema migrations you rehearsed on
+   staging are still pending in the live database's journal — they apply now,
+   with an automatic pre-promote snapshot taken first. A migration failure
+   aborts the promote: the live version never flips, old code keeps running,
+   and the output names the snapshot and the restore command.
+2. **The staged backend goes live.** If the version shipped a worker, the
+   platform redeploys that exact bundle with live bindings.
+3. **The pointer flips.** The staged version becomes the live version.
+
+The output confirms the live URL, the promoted version, any migrations that
+applied, and the snapshot key.
+
+Promotion is also a button on the dashboard's Overview tab.
+
+See also [canopy deploy](https://docs.canopy.website/cli/deploy) (`--staging`), [canopy staging](https://docs.canopy.website/cli/staging),
+and [Staging & promoting](https://docs.canopy.website/guides/staging).

package/dist/docs/cli-rollback.md

@@ -0,0 +1,45 @@
+---
+title: canopy rollback
+description: Make an earlier deploy live again by moving the live pointer to a previous version.
+---
+
+`canopy rollback` switches the project's live version back to an earlier deploy. Reach for it when a deploy went wrong and you want the last good version serving again in seconds — no rebuild, no re-upload.
+
+## Usage
+
+```bash
+canopy rollback                 # pick a version from the deploy history
+canopy rollback v3              # make v3 live directly
+canopy rollback --project my-app 3
+```
+
+## Arguments & flags
+
+- `[version]` — the deploy version to make live, as `3` or `v3`. Optional: when omitted on an interactive terminal you get a picker showing the full deploy history (version, timestamp, source, and which one is currently live), preselecting the version just before the live one. On a non-TTY run with no version, the CLI rolls back to `live - 1` automatically.
+- `--project <slug>` — project slug, overriding `canopy.json` in the target directory.
+- `--dir <path>` — project directory (defaults to the current directory).
+- `--profile <site>` / `CANOPY_PROFILE` — which site's deployment to roll back.
+
+## How it works
+
+Every deploy is stored immutably as a numbered version; "live" is just a pointer to one of them. Rolling back moves that pointer — no files are rebuilt, uploaded, or deleted. Projects with a custom backend also get their backend rolled to the bundle matching the target version, so frontend and backend stay in step. The command prints the target, asks the platform to repoint, and confirms with the live URL, the now-live version, and the version that was live before.
+
+Because versions are never destroyed, rolling back is symmetric: "roll forward" is simply `canopy rollback <newer-version>` — pass the number of the newer deploy you want live again. Picking the version that's already live is an error, and a project with fewer than two deploys has nothing to roll back to.
+
+Deploy history is also visible in the dashboard, where the same rollback is a button.
+
+## Examples
+
+```bash
+canopy rollback
+```
+
+Shows the deploy history for the project in the current directory and lets you pick — the entry before the live one is preselected.
+
+```bash
+canopy rollback v7 --project client-site --profile main
+```
+
+Directly repoints `client-site` on the main site to version 7 — works the same whether v7 is older or newer than what's live.
+
+See also [canopy deploy](https://docs.canopy.website/cli/deploy), [canopy download](https://docs.canopy.website/cli/download), and [Deploys & rollbacks](https://docs.canopy.website/platform/deploys-and-rollbacks).

package/dist/docs/cli-skill.md

@@ -0,0 +1,39 @@
+---
+title: canopy skill
+description: Install the Canopy agent skill into a repo so coding agents know how to drive the platform.
+---
+
+`canopy skill install` writes the Canopy agent skill into the current repository, teaching AI coding agents (Claude Code and others) how to use the platform: checking install and login state, creating vs. initializing projects, choosing templates, reading `canopy docs` before guessing, and treating `db restore`, `delete`, and deploys with appropriate care.
+
+## Usage
+
+```bash
+canopy skill install
+```
+
+`install` is currently the only subcommand.
+
+## Arguments & flags
+
+None — it always installs into the repository at the current working directory.
+
+## How it works
+
+The skill files ship inside the CLI package, so installing needs no network. Two paths are written:
+
+- `.agents/skills/canopy/` — the source of truth, in the tool-neutral `.agents/` tree so any agent tooling can read it (no vendor lock-in).
+- `.claude/skills/canopy` — a **symlink** to the `.agents/` copy, so Claude Code picks the skill up. Where symlinks aren't available (e.g. Windows without developer mode), the CLI falls back to a real copy and says so.
+
+Installation is a clean replace: any existing skill directory is removed first, and the installed copy is stamped with the CLI version that wrote it. That stamp is how the skill stays fresh — [`canopy upgrade`](https://docs.canopy.website/cli/upgrade) detects an installed skill in the repo and re-runs `canopy skill install` with the new CLI, so the skill always matches the CLI version in use. If that auto-refresh ever fails, re-run `canopy skill install` yourself.
+
+Commit the `.agents/` directory (and the `.claude/` link) so teammates and CI agents get the skill with the repo.
+
+## Examples
+
+```bash
+canopy skill install
+```
+
+From a repo root: installs the skill, prints where the files went and whether `.claude/skills/canopy` is a symlink or a copy, and suggests trying `canopy docs`.
+
+See also [canopy docs](https://docs.canopy.website/cli/docs) — the always-current documentation the skill points agents at — and [canopy upgrade](https://docs.canopy.website/cli/upgrade).

package/dist/docs/cli-staging.md

@@ -0,0 +1,54 @@
+---
+title: canopy staging
+description: Inspect, refresh, or tear down the project's staging channel.
+---
+
+`canopy staging` manages the project's [staging channel](https://docs.canopy.website/guides/staging) — the
+safe copy created by the first `canopy deploy --staging`.
+
+## Usage
+
+```bash
+canopy staging status           # what's staged, what's live, the staging URL
+canopy staging use v3           # serve an existing version on staging
+canopy staging sync             # replace staging data with a fresh copy of live
+canopy staging destroy          # remove the staging channel entirely
+```
+
+## Subcommands
+
+### `status`
+
+Shows whether the channel exists, which version is staged (and whether it has
+a backend), which version is live, and the staging URL. When the staged version
+differs from live it reminds you that `canopy promote` makes it live.
+
+### `use`
+
+Points the staging channel at any version in the deploy history — the reverse
+of [canopy promote](https://docs.canopy.website/cli/promote), and the staging twin of
+[canopy rollback](https://docs.canopy.website/cli/rollback). A pointer move: nothing is uploaded or
+rebuilt, and the version's backend (if any) is redeployed to the staging
+worker. Omit the version on a terminal to pick from the history. Requires the
+staging channel to exist; it applies no migrations, so an old version runs
+against staging's current schema (the same caveat version previews have).
+
+### `sync`
+
+Re-clones the live database over the staging one. Staging data is replaced —
+live is only read. Use it to re-rehearse a migration on fresh data, or when
+test writes have made staging drift too far. Asks for confirmation on a
+terminal; `--yes` skips it.
+
+### `destroy`
+
+Deletes the staging database, staged files, and the staging backend. Live is
+untouched. The deploy history keeps its records, and the next
+`canopy deploy --staging` recreates the channel from a fresh copy of live.
+Requires typing the slug to confirm; `--yes` skips it.
+
+All three take `--project <slug>` to target a project outside the current
+directory, and `--profile <site>` / `CANOPY_PROFILE` for the site.
+
+See also [canopy deploy](https://docs.canopy.website/cli/deploy), [canopy promote](https://docs.canopy.website/cli/promote), and
+[Staging & promoting](https://docs.canopy.website/guides/staging).

package/dist/docs/cli-token.md

@@ -0,0 +1,47 @@
+---
+title: canopy token
+description: Create, list, and revoke project-scoped deploy tokens for CI and push-to-main deploys.
+---
+
+`canopy token` manages deploy tokens: standing `cnpy_` bearer credentials that can do exactly one thing — deploy one specific project. You reach for it when setting up CI (typically GitHub Actions deploying on every push to main) so the runner never needs a personal login.
+
+## Usage
+
+```bash
+canopy token create --name "GitHub Actions"
+canopy token list
+canopy token revoke <id>
+```
+
+## Arguments & flags
+
+All subcommands resolve the project the usual way — `canopy.json` in the target directory, or `--project <slug>` to override — and honor the global `--profile <site>` / `CANOPY_PROFILE` for which site the token belongs to.
+
+- `create` — mint a new deploy token for the project.
+  - `--name <label>` — a label shown in the dashboard, e.g. `"GitHub Actions"`. Optional but recommended so you can tell tokens apart later.
+- `list` — show the project's deploy tokens: id, name, creation time, and who created them. Token values are never shown here.
+- `revoke <id>` — delete a token by its id (from `canopy token list`). Deploys using it stop working immediately.
+
+## How it works
+
+`create` prints the token plaintext **exactly once** — the platform stores only a hash, so copy it right away. The token is scoped to a single project on a single site: it can deploy that project and nothing else, which makes it safe to hand to a CI system.
+
+To use it in CI, put the value in the `CANOPY_DEPLOY_TOKEN` environment variable — the CLI checks it before the login token, so `canopy deploy` works on a runner with no `canopy login`. For GitHub Actions, add it as the repo secret `CANOPY_DEPLOY_TOKEN` (`gh secret set CANOPY_DEPLOY_TOKEN`, or Settings → Secrets); pushes to main then deploy via the project's `canopy-deploy.yml` workflow.
+
+If a deploy fails with a rejected token, it was likely revoked — create a fresh one here or in the dashboard (Settings → Deploy tokens) and update the secret. Losing a token is never a problem: revoke the old id and mint a new one.
+
+## Examples
+
+```bash
+canopy token create --name "GitHub Actions"
+```
+
+Prints a new `cnpy_` token once, with instructions for storing it as the `CANOPY_DEPLOY_TOKEN` repo secret.
+
+```bash
+canopy token list --project my-app
+```
+
+Shows every deploy token for `my-app` so you can spot stale ones and revoke them by id.
+
+See also [canopy deploy](https://docs.canopy.website/cli/deploy) and the [CI guide](https://docs.canopy.website/guides/ci).

package/dist/docs/cli-upgrade.md

@@ -0,0 +1,43 @@
+---
+title: canopy upgrade
+description: Update the Canopy CLI to the latest published version, using the installer that put it there.
+---
+
+`canopy upgrade` reinstalls the CLI globally at the latest published version. You'll usually run it because the CLI told you to: when a newer release exists, commands print a one-line `Update available: … Run 'canopy upgrade' to update.` hint on stderr.
+
+## Usage
+
+```bash
+canopy upgrade
+canopy upgrade --version 0.5.0
+canopy upgrade --pm npm
+```
+
+## Arguments & flags
+
+- `--version <x.y.z>` — install this exact version instead of `latest` (also how you downgrade).
+- `--pm <installer>` — which installer to use: `vp`, `npm`, `pnpm`, `yarn`, or `bun`. Auto-detected by default.
+
+## How it works
+
+The CLI shells out to a package manager rather than replacing files itself, so global prefixes, permissions, and lockfiles stay the installer's concern. It detects which installer owns the running binary from the binary's own path (Vite+, pnpm, bun, and yarn each keep globals in a recognizable place) and defaults to npm otherwise. The detection matters: a Vite+-installed `canopy` upgraded via plain `npm install -g` would land in npm's separate prefix and leave the active binary untouched — `--pm` overrides the guess when it's wrong.
+
+The command prints the exact install command it runs, streams the installer's output, and suggests `canopy --version` to confirm. If the repo you're in has the [Canopy agent skill](https://docs.canopy.website/cli/skill) installed, the upgrade finishes by running the **new** CLI's `canopy skill install` to keep the skill in sync (with a warning, not a failure, if that step can't run).
+
+The passive hint that leads you here is a once-a-day background check of the npm registry, cached in `~/.canopy/version-check.json`. It never blocks or slows a command, stays silent in CI and piped output, and can be disabled with `CANOPY_NO_UPDATE_CHECK=1`. The hint itself is suppressed while you're running `upgrade`.
+
+## Examples
+
+```bash
+canopy upgrade
+```
+
+Detects that the CLI was installed with, say, Vite+ and runs `vp install -g @mediamonks/canopy-cli@latest`, then refreshes the repo's agent skill if one is installed.
+
+```bash
+canopy upgrade --version 0.5.0 --pm npm
+```
+
+Pins a specific release through npm — useful to roll back a release or to correct a wrong auto-detection.
+
+See also [canopy skill](https://docs.canopy.website/cli/skill) and [Installing the CLI](https://docs.canopy.website/cli).

package/dist/docs/cli-usage.md

@@ -0,0 +1,43 @@
+---
+title: canopy usage
+description: Show a project's AI spend, storage footprint, and deploy count from the terminal.
+---
+
+`canopy usage` prints what a project is consuming — the same data as the dashboard's Usage tab, without leaving the terminal. Reach for it when you want to know what the AI features are costing, how big the database and blob store have grown, or which version is live.
+
+## Usage
+
+```bash
+canopy usage [--project <slug>] [--json]
+```
+
+## Arguments & flags
+
+- `--project <slug>` — project slug. Defaults to the `canopy.json` in the current directory.
+- `--json` — print the raw JSON (same shape as the dashboard Usage API) instead of the formatted report. Default `false`.
+
+## How it works
+
+The command resolves the project, fetches its usage from the platform, and prints a report covering (by default) the last 30 days:
+
+- **AI** — total spend in USD, request count, and tokens in/out, with a per-model breakdown (top 8 models). If AI usage data isn't available for the project, the report says so with the reason. A note appears when the window held more requests than were summarized.
+- **Storage** — database size and table count, and blob storage total bytes and object count (each shown as `—` when the project has none).
+- **Deploys** — how many deploys the project has had, and which version is currently live.
+
+It's read-only: nothing is changed, and no confirmation is needed. With `--json`, the report goes to stdout as `{ slug, usage }` for scripts and agents; the human view is plain text either way.
+
+## Examples
+
+```bash
+canopy usage
+```
+
+From inside a project directory: prints the AI spend, storage, and deploy summary for the project pinned in `canopy.json`.
+
+```bash
+canopy usage --project my-app --json | jq .usage.ai.costUsd
+```
+
+Pulls one number — the project's AI spend over the window — for a script or a quick answer.
+
+See also [AI usage](https://docs.canopy.website/platform/ai-usage) for how spend is measured, and [canopy projects](https://docs.canopy.website/cli/projects) to find a slug.