@mediamonks/canopy-cli 0.7.5 → 0.7.6

package/dist/docs/cli-create.md

@@ -0,0 +1,46 @@
+---
+title: canopy create
+description: Register a new project on Canopy and scaffold it locally from a starter template.
+---
+
+`canopy create` is the start of every new project: it registers the project on Canopy (claiming its slug and live URL) and scaffolds a runnable starter into `./<slug>/`. Everything is prompted for interactively, or passable as flags for scripted use.
+
+## Usage
+
+```bash
+canopy create                             # fully interactive
+canopy create "My Portfolio" --slug my-portfolio --template spa
+canopy create existing-app --no-scaffold  # register only, no files written
+```
+
+## Arguments & flags
+
+- `<name>` — the project's display name. Multi-word names work unquoted (every positional joins the name). Prompted for when omitted on a TTY.
+- `--slug <slug>` — the URL slug; the project will live at `https://<slug>.<site-domain>`. Lowercase letters, digits and dashes only. Defaults to a slugified version of the name (prompted on a TTY).
+- `--template <id>` — starter to scaffold: `static` (plain HTML/CSS/JS, no build step, untyped SDK from the platform — simplest apps), `spa` (Vite + React + TypeScript with the typed SDK from npm — best for real SDK use or growth), or `worker` (`spa` plus a backend worker in `worker/` — for server-side code: secrets, schedules, calling external APIs). A picker appears when omitted on a TTY; `static` is the default otherwise.
+- `--scaffold` / `--no-scaffold` — whether to write `./<slug>/` from the template. When neither is given, the CLI scaffolds unless the current directory already has a `canopy.json` (in which case it assumes you're registering an existing app and only registers).
+- `--profile <site>` — global flag (or `CANOPY_PROFILE`): which site to create the project on. The chosen profile is pinned into the scaffolded `canopy.json`.
+
+## How it works
+
+The project is registered with the platform first — this is what reserves the slug and creates the entry you'll see in `canopy projects` and the dashboard. Taken, reserved, or invalid slugs fail here with an actionable error, before anything touches disk.
+
+With scaffolding on, the CLI then copies the template into `./<slug>/` (refusing if that directory already exists), substituting the name and slug into the files, and writes a `canopy.json` containing the slug and the profile pin. Templates ship a README, an `AGENTS.md`, and a `.gitignore`; the `spa` template also needs an `npm install` before `canopy dev`. With `--no-scaffold`, nothing is written — an existing `canopy.json` is left untouched, and you're told to add one if the directory has none.
+
+The live URL is printed at the end, but it only serves content after your first `canopy deploy`.
+
+## Examples
+
+```bash
+canopy create
+```
+
+Walks you through name, slug, and template, registers the project, and scaffolds a ready-to-run starter with next steps printed.
+
+```bash
+canopy create "Team Retro Board" --slug retro-board --template spa
+```
+
+Registers `retro-board`, scaffolds a React SPA into `./retro-board/`, and tells you to `npm install` then `canopy dev`.
+
+To set up a local folder for a project that already exists on Canopy, use [canopy init](https://docs.canopy.website/cli/init) instead. See also [canopy projects](https://docs.canopy.website/cli/projects) and [canopy delete](https://docs.canopy.website/cli/delete).

package/dist/docs/cli-db.md

@@ -0,0 +1,86 @@
+---
+title: canopy db
+description: Pull, snapshot, list, restore, and migrate a project's database from the terminal.
+---
+
+`canopy db` is the data-safety toolbox: export the project database as SQL, store restorable snapshots server-side, restore from either, and apply schema migrations. The project comes from `canopy.json` in the current directory, or from `--project <slug>` on any subcommand.
+
+The habit that makes restores safe: **always `canopy db snapshot` before `canopy db restore`**. A restore replaces everything, and a snapshot taken seconds earlier is your undo button.
+
+## Usage
+
+```bash
+canopy db pull [--out <file>] [--project <slug>]
+canopy db snapshot [--project <slug>]
+canopy db snapshots [--project <slug>]
+canopy db restore [file.sql] [--snapshot <key>] [--yes] [--project <slug>]
+canopy db migrate [--plan] [--project <slug>]
+```
+
+All subcommands accept `--project <slug>` (overrides `canopy.json` in the
+current directory), and `--staging` to operate on the
+[staging channel's](https://docs.canopy.website/guides/staging) database instead of live — its snapshots
+live in their own history, and `db migrate --staging` is the migration
+rehearsal.
+
+### canopy db pull
+
+Downloads a fresh SQL dump of the project database to a local file.
+
+- `--out <file>` — output path. Defaults to `<slug>-<timestamp>.sql` in the current directory.
+
+The platform exports the database and hands the CLI a download URL; the CLI fetches it and writes the file, reporting its size. Use this for local inspection, ad-hoc backups, or as input to a later `db restore`.
+
+### canopy db snapshot
+
+Stores a dump **server-side**, restorable anytime from the CLI or the dashboard. No flags beyond `--project`. On success it prints the snapshot key and size, plus the exact `canopy db restore --snapshot <key>` command to bring it back. Take one before every restore, schema experiment, or bulk data change.
+
+### canopy db snapshots
+
+Lists stored snapshots for the project — one line per snapshot with its key, size, and creation time. If there are none yet, it points you at `canopy db snapshot`.
+
+### canopy db restore
+
+Replaces **all** current project data from a snapshot or a local `.sql` file.
+
+- `[file.sql]` — positional: a local SQL dump to restore from.
+- `--snapshot <key>` — a server-side snapshot key to restore from instead.
+- `--yes` — skip the confirmation (default `false`).
+
+Behavior:
+
+1. With neither a file nor `--snapshot`, and on an interactive terminal, it fetches the stored snapshots and lets you pick one. On a non-TTY you must pass a source explicitly.
+2. Unless `--yes` is passed, it asks you to **type the project slug** to confirm — a deliberate speed bump, since restore is destructive. A non-TTY without `--yes` errors instead of guessing.
+3. The chosen snapshot or file replaces the entire database, and the CLI confirms `Restored <slug>.`
+
+### canopy db migrate
+
+Applies pending schema migrations to the project's **live** database, without deploying. Requires a `"migrations"` directory in `canopy.json` (for example your `drizzle-kit generate` output — see the [migrations guide](https://docs.canopy.website/guides/migrations)).
+
+- `--plan` — dry run: lists what would apply, touches nothing.
+
+Migration files are ordered `.sql` files, applied in filename order and journaled in the database, so each file applies exactly once. The platform stores an automatic **pre-migrate snapshot** before applying anything — a botched migration is one `canopy db restore` away. Files that were already applied must not be edited afterwards (write a new migration instead); the platform refuses edited history.
+
+Normally you won't run this yourself: `canopy deploy` applies pending migrations automatically so schema and code ship together. `canopy db migrate` exists for applying schema changes without a deploy, and for CI.
+
+## Examples
+
+```bash
+canopy db snapshot && canopy db pull
+```
+
+Belt and braces before risky work: a server-side snapshot you can restore from the dashboard, plus a local dump on disk.
+
+```bash
+canopy db restore --snapshot snap-2026-08-11-1200 --yes --project my-app
+```
+
+Non-interactive restore (for scripts): restores the named snapshot into `my-app` without the typed confirmation — only sensible right after taking it.
+
+```bash
+canopy db restore seed.sql
+```
+
+Loads a local dump — for example a seed file — after the type-the-slug confirmation.
+
+See also the [Data guide](https://docs.canopy.website/guides/data) and [Project data](https://docs.canopy.website/platform/project-data) for how the database, snapshots, and blobs fit together.

package/dist/docs/cli-delete.md

@@ -0,0 +1,44 @@
+---
+title: canopy delete
+description: Permanently delete a Canopy project — its deploys, database, and files.
+---
+
+`canopy delete` removes a project from Canopy entirely: the live site stops serving, and its deploy history, database, and stored files are torn down. It is not a pause or an archive — there is no undo, and nothing to restore from afterwards.
+
+## Usage
+
+```bash
+canopy delete my-project
+canopy delete my-project --yes   # skip the confirmation (scripts/agents)
+canopy delete                    # pick from a list of your projects
+```
+
+## Arguments & flags
+
+- `<slug>` — the project to delete. When omitted on a TTY, you pick from a list of projects you can actually delete (deleting is owner-level: owners see their own projects, admins see all).
+- `--yes` — skip the type-the-slug confirmation. Required on non-interactive runs; use with care, since it removes the last safeguard.
+- `--profile <site>` — global flag (or `CANOPY_PROFILE`): sites are independent, so make sure you're deleting on the site you mean. Deleting a project on `main` does not touch a same-named project on `staging`.
+
+## Details
+
+Without `--yes`, the CLI asks you to **type the slug back exactly** to confirm; anything else aborts with no changes. On a non-TTY, omitting `--yes` (or the slug) is an error rather than a hang.
+
+Once confirmed, the platform tears the project down completely: the project itself, its deploys (so rollback targets are gone too), its database, and its uploaded files. Your local project directory is **not** touched — the code on disk survives, only the platform side is destroyed. That local copy is your only remaining artifact, so if you might want the data later, pull a database snapshot first.
+
+Only project owners (and site admins) can delete; the platform refuses the request otherwise.
+
+## Examples
+
+```bash
+canopy delete old-prototype
+```
+
+Prompts you to type `old-prototype` to confirm, then tears the project down and prints a success line.
+
+```bash
+canopy delete scratch-test --yes --profile staging
+```
+
+Deletes without prompting — the pattern for cleaning up scratch projects in scripts, made explicit about which site it hits.
+
+See also [canopy projects](https://docs.canopy.website/cli/projects) to find slugs, and [Project data](https://docs.canopy.website/platform/project-data) for what a project stores.

package/dist/docs/cli-deploy.md

@@ -0,0 +1,58 @@
+---
+title: canopy deploy
+description: Build the project and push a new version live, from your machine or from CI.
+---
+
+`canopy deploy` builds your project (if `canopy.json` defines a build command), uploads the output directory, and makes the new version live at the project's URL. It's the same command whether you run it by hand or from a CI runner with a deploy token.
+
+## Usage
+
+```bash
+canopy deploy                       # build, upload, go live
+canopy deploy --no-build            # deploy the output directory as-is
+canopy deploy --project my-app ./out
+```
+
+## Arguments & flags
+
+- `[dir]` — project directory (defaults to the current directory).
+- `--project <slug>` — project slug, overriding `canopy.json`. With `--project`, a `canopy.json` is optional — you can deploy any static directory; when one exists it still supplies `build` and `dist`.
+- `--build` / `--no-build` — run the `canopy.json` build command first (default on). Use `--no-build` when the output is already built, e.g. a CI step that built earlier.
+- `--migrate` / `--no-migrate` — apply pending schema migrations before the new version goes live (default on; only does anything when `canopy.json` configures a `"migrations"` directory — see the [migrations guide](https://docs.canopy.website/guides/migrations)).
+- `--staging` — deploy to the project's [staging channel](https://docs.canopy.website/guides/staging) instead of live: created on first use with a copy of the live database, served at `staging-dot-<slug>`, promoted with [canopy promote](https://docs.canopy.website/cli/promote). Pending migrations apply to the _staging_ database (the rehearsal). Not to be confused with `--profile staging`, which picks a whole different site.
+- `--profile <site>` / `CANOPY_PROFILE` — which site to deploy to (`main`, `staging`, …). Always pass it explicitly when the target matters; a `canopy.json` profile pin is the fallback.
+
+## How it works
+
+1. **Build.** If `canopy.json` has a `build` command and you didn't pass `--no-build`, it runs in the project directory with your shell; a non-zero exit aborts the deploy.
+2. **Collect files.** Everything under the `dist` directory from `canopy.json` (default: the project directory itself) is gathered, skipping `canopy.json`, `README.md`, `AGENTS.md`, `CLAUDE.md`, `.gitignore`, `.DS_Store`, and any dot-directories plus `.git`, `node_modules`, and `.claude`. An empty or missing output directory is an error.
+3. **Bundle the backend (if any).** When `canopy.json` names a `worker` entry, that backend code is bundled into a single file (dependencies included) and ships in the same version as the static files — frontend and backend always move together.
+4. **Upload.** The files upload in parallel; the new version is staged alongside the old one, so the live site keeps serving until everything has arrived.
+5. **Migrate (if configured).** With a `"migrations"` directory in `canopy.json`, pending schema migrations apply now — after the bundle is staged, before the version flips — so the incoming code never runs against the old schema. The platform stores an automatic pre-migrate snapshot first. If a migration fails, the deploy aborts and the live version is unchanged; the error names the snapshot to restore if needed.
+6. **Go live.** The platform validates the staged version and switches the site over to it in one step. The upload must contain an `index.html` at the top level — the deploy is rejected otherwise — so double-check `dist` points at the folder that actually holds `index.html`. On success the CLI prints the live URL and version number (plus the backend service URL for worker projects).
+
+Deploys are versioned and immutable: nothing overwrites an old version, so [canopy rollback](https://docs.canopy.website/cli/rollback) can always take you back.
+
+**CI.** Set the `CANOPY_DEPLOY_TOKEN` environment variable to a project-scoped deploy token (from [canopy token create](https://docs.canopy.website/cli/token)) and `canopy deploy` works with no `canopy login` — the token can deploy exactly one project and nothing else. Deploys from GitHub Actions are tagged with their source in the deploy history.
+
+## Examples
+
+```bash
+canopy deploy
+```
+
+From a project directory: runs the build from `canopy.json`, uploads the `dist` output, and prints the live URL with the new version number.
+
+```bash
+canopy deploy --profile staging
+```
+
+Same project, deployed to the staging site instead of the profile pinned in `canopy.json`.
+
+```bash
+CANOPY_DEPLOY_TOKEN=cnpy_… canopy deploy --no-build
+```
+
+A CI step deploying already-built output with a deploy token — no interactive login involved.
+
+See also [canopy rollback](https://docs.canopy.website/cli/rollback), [canopy token](https://docs.canopy.website/cli/token), the [deploy guide](https://docs.canopy.website/guides/deploy), and [CI setup](https://docs.canopy.website/guides/ci).

package/dist/docs/cli-dev.md

@@ -0,0 +1,63 @@
+---
+title: canopy dev
+description: Run your project locally with a Vite dev server, against live platform data or a local sandbox.
+---
+
+`canopy dev` starts a Vite dev server for the project directory and wires up `/_api` so the SDK works exactly as it does in production. By default it's remote-first: your local pages talk to the **live** platform API and see the same data the deployed app sees. When you'd rather experiment on a disposable copy, `--local` swaps in a sandbox on your machine.
+
+## Usage
+
+```bash
+canopy dev                      # remote-first: live project data
+canopy dev --local              # local sandbox: your data stays on your machine
+canopy dev --local --pull       # sandbox hydrated from a fresh prod export
+```
+
+## Arguments & flags
+
+- `[dir]` — project directory (defaults to the current directory). Needs a `canopy.json` unless you pass `--project`.
+- `--project <slug>` — project slug, overriding the `canopy.json` in the target directory.
+- `--port <n>` — dev server port (Vite picks one when omitted).
+- `--local` — use the local-data sandbox instead of live data. Default off.
+- `--pull` — hydrate the sandbox from a fresh export of the project's production database first. Only valid with `--local`; the command errors otherwise (remote dev already sees live data).
+- `--staging` — point remote dev at the [staging channel's](https://docs.canopy.website/guides/staging) data instead of live (the safe remote target while a schema is in flux), or, with `--local --pull`, hydrate the sandbox from the staging dump.
+- `--profile <site>` / `CANOPY_PROFILE` — which site the dev token and API calls target. Projects usually pin a profile in `canopy.json`.
+
+## How it works
+
+**Remote-first (default).** The CLI mints a short-lived, project-scoped dev token from the platform, then starts Vite with a proxy: every `/_api/*` request is forwarded to the real platform API with that token attached. The token stays inside the proxy — browser code never holds a credential. When the token expires (the expiry is printed at startup), restart `canopy dev`. Because you're on live data, the startup banner suggests `canopy db snapshot` before risky changes, or switching to `--local --pull`.
+
+**Local sandbox (`--local`).** Database, file, and auth requests are answered entirely on your machine, from a sandbox stored under `.canopy/local/` in the project directory — no database to install, and writes never reach the platform. The sandbox behaves the same as the real API, so code that works locally works deployed. Two things still go remote: `ai` and `services` calls go through to the real platform (metered as usual) when you're logged in — fully offline, they return errors until you log in and restart.
+
+**Matching your site's SQL dialect.** The document API (`canopy.db.collection(…)`) behaves identically everywhere, but raw `canopy.db.sql()` speaks the deployment target's dialect — SQLite on Cloudflare-backed sites, Postgres on GCP-backed ones (see [dialect()](https://docs.canopy.website/guides/data)). The sandbox defaults to Postgres. If your project uses raw SQL written for a SQLite site, lock the dialect in `canopy.json`:
+
+```json
+{ "slug": "my-project", "dialect": "sqlite" }
+```
+
+With the lock in place, `--local` runs on an embedded SQLite engine instead — the same raw SQL, full-text search behavior, and `--pull` dumps as your deployed site. `"dialect": "postgres"` makes today's default explicit. Each engine keeps its own state under `.canopy/local/`, so switching the lock never corrupts data. The SQLite engine uses Node's built-in database and needs **Node 24+** (older Node builds lack full-text search); the CLI says so plainly if yours is older.
+
+**`--pull`.** Before the sandbox boots, the CLI requests a fresh SQL export of the project's production database and applies it locally. Sync is pull-only — nothing ever pushes back. Blobs are not pulled; the local blob store starts empty.
+
+**Schema migrations.** When `canopy.json` configures a `"migrations"` directory (see the [migrations guide](https://docs.canopy.website/guides/migrations)), the `--local` sandbox applies pending migrations on boot, so the local schema always matches the repo. Remote-first dev **never** applies migrations — it points at production, and schema changes ship with `canopy deploy`. While a schema change is in flux, work in `--local`.
+
+A few practical notes:
+
+- If your project ships its own Vite (the spa and worker scaffolds do), `canopy dev` uses that install and merges your `vite.config`; the `/_api` proxy always wins. The no-build static scaffold falls back to the CLI's bundled Vite.
+- If the slug in `canopy.json` isn't registered on Canopy (or your account can't access it), the dev-token lookup fails with instructions to either fix the slug or create the project in the dashboard.
+
+## Examples
+
+```bash
+canopy dev
+```
+
+Serves the current directory and proxies `/_api` to the live project — good for day-to-day work where you want real data.
+
+```bash
+canopy dev --local --pull --port 3000
+```
+
+Pulls a fresh copy of production data into `.canopy/local/`, then serves the app on port 3000 against that copy — safe for destructive experiments.
+
+See also [canopy deploy](https://docs.canopy.website/cli/deploy) and the [local development guide](https://docs.canopy.website/guides/dev).

package/dist/docs/cli-docs.md

@@ -0,0 +1,47 @@
+---
+title: canopy docs
+description: Read the Canopy docs from the terminal — live from the platform, with offline fallbacks.
+---
+
+`canopy docs` lists and prints the full Canopy documentation in the terminal — the same content as this site, section by section: the overview, the guides, the platform pages, and the CLI and SDK references. It's built for agents and humans alike: the content is served live by the platform so it never goes stale, but the command still works offline and before you've ever signed in.
+
+## Usage
+
+```bash
+canopy docs                 # list all topics
+canopy docs <topic>         # print one topic
+canopy docs <topic> --refresh
+```
+
+## Arguments & flags
+
+- `[topic]` — positional: the topic slug to print. Omit it to list every topic with a one-line summary, grouped by section. Guides keep bare slugs (`deploy`, `staging`); other sections prefix theirs (`sdk-database`, `cli-deploy`, `platform-schedules`).
+- `--refresh` — re-fetch from the platform, bypassing the local cache. Default `false`.
+
+## How it works
+
+Content resolves in a fixed fallback order:
+
+1. **Platform** — fetched live (topics are cached for an hour; `--refresh` forces a fetch). Requests carry your CLI token or `CANOPY_DEPLOY_TOKEN` when one exists, since platform docs require a login.
+2. **Local cache** — `~/.canopy/docs-cache/`, filled by every successful platform fetch.
+3. **Bundled snapshot** — a copy of the docs shipped inside the CLI package itself.
+
+That last step is why `canopy docs` works with no network and no login: a fresh install always has the bundled snapshot, and it only gets fresher from there. Fetches time out after a few seconds and fall through silently, so a flaky connection degrades to slightly older docs rather than an error.
+
+Asking for an unknown topic errors with the list of available slugs. Everything prints as plain Markdown to stdout, so it pipes cleanly into a pager or an agent's context.
+
+## Examples
+
+```bash
+canopy docs
+```
+
+Lists every topic with its summary — the starting point when you're not sure which guide covers what you're doing.
+
+```bash
+canopy docs deploy --refresh
+```
+
+Prints the deploy guide, guaranteed fresh from the platform rather than the hour-old cache.
+
+See also [canopy skill](https://docs.canopy.website/cli/skill), which teaches coding agents to reach for `canopy docs` on their own.

package/dist/docs/cli-download.md

@@ -0,0 +1,42 @@
+---
+title: canopy download
+description: Download the deployed files of any version of a project as a zip archive.
+---
+
+`canopy download` fetches the exact files a deploy is serving — the live version by default, or any version from the history — and writes them to a zip on your machine. Useful for recovering a project whose source you've lost, auditing what's actually live, or diffing two versions.
+
+## Usage
+
+```bash
+canopy download                     # the live version (or pick from history)
+canopy download v3                  # a specific version
+canopy download --project my-app --out backup.zip
+```
+
+## Arguments & flags
+
+- `[version]` — the deploy version to download, as `3` or `v3`. Optional: on an interactive terminal you get a picker over the deploy history with the live version preselected; on a non-TTY run the live version is taken automatically (an error if the project has no live version — pass one explicitly).
+- `--out <file>` — output file path. Defaults to `<slug>-v<version>.zip` in the current directory.
+- `--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 to download from.
+
+## How it works
+
+The CLI resolves the target version (argument, picker, or live), asks the platform for that deploy's assets as a zip, and writes the archive to `--out`. The zip contains the deployed bundle as uploaded — the static files, and for worker projects the bundled `_canopy/worker.mjs`. It does not include files [canopy deploy](https://docs.canopy.website/cli/deploy) skips (like `canopy.json` itself), nor your project's database or blobs — those are handled by the data tooling, not deploy versions. A project with no deploys yet has nothing to download.
+
+## Examples
+
+```bash
+canopy download
+```
+
+From a project directory: pick a version from history (live preselected) and get e.g. `my-app-v5.zip` next to you, with the written size reported.
+
+```bash
+canopy download v2 --project legacy-site --out /tmp/legacy-v2.zip
+```
+
+Grabs version 2 of another project without needing its directory, writing to an explicit path — handy before comparing it against what's live now.
+
+See also [canopy deploy](https://docs.canopy.website/cli/deploy), [canopy rollback](https://docs.canopy.website/cli/rollback), and [Deploys & rollbacks](https://docs.canopy.website/platform/deploys-and-rollbacks).

package/dist/docs/cli-egress.md

@@ -0,0 +1,37 @@
+---
+title: canopy egress
+description: Manage which outbound hosts the project's backend worker may fetch.
+---
+
+`canopy egress` manages the project's outbound-host allowlist. Worker `fetch`
+calls to hosts outside the list are denied (`egress_denied`) — see
+[Outbound requests](https://docs.canopy.website/platform/egress).
+
+## Usage
+
+```bash
+canopy egress list
+canopy egress allow api.example.com
+canopy egress allow "*.googleapis.com"
+canopy egress remove api.example.com
+```
+
+## 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`.
+
+- `list` — print the allowed hosts, one per line.
+- `allow <host>` — add a hostname (or `*.` subdomain wildcard; quote it so the
+  shell doesn't expand the `*`).
+- `remove <host>` — remove an entry (as shown by `list`).
+
+## How it works
+
+The list lives on the platform, per project, shared by the live and staging
+channels — deliberately **not** in `canopy.json`, so a repo file can never
+widen egress silently on deploy. Changes re-roll the running workers
+immediately; no deploy is needed. Entries are validated server-side: bare
+hostnames or `*.` wildcards only, no IPs, ports, schemes, or paths, at most 32
+entries.

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).