@mediamonks/canopy-cli 0.7.12 → 0.7.13

package/dist/docs/cli-whoami.md

@@ -0,0 +1,46 @@
+---
+title: canopy whoami
+description: Show which account and site the CLI is currently talking to, and whether your token is still valid.
+---
+
+`canopy whoami` prints the login the CLI would use right now: your email, the API it points at, and your token's expiry. Reach for it when a command fails with an auth error, or to double-check which site you're about to act on.
+
+## Usage
+
+```bash
+canopy whoami
+canopy --profile staging whoami   # check a specific site's token
+```
+
+## Arguments & flags
+
+- `--profile <site>` — global flag (or `CANOPY_PROFILE`): check the token for a specific site instead of your resolved default. Each site has its own token, so being logged in on `main` says nothing about `staging`.
+
+## Details
+
+The command is fully offline — it only reads `~/.canopy/config.json`, no network calls. For the resolved profile it prints:
+
+- your email (as recorded at login),
+- the cloud the site runs on, when known,
+- the API URL the CLI targets,
+- the token expiry — either `Token expires <date>` or a loud `Token EXPIRED` line telling you to run `canopy login` again.
+
+The active site and CLI version are printed on stderr as a header line by every command, `whoami` included. If no token is stored for the resolved profile, the command exits with an error suggesting `canopy login`.
+
+Note that expiry is checked against the stored timestamp only; a token can also be revoked server-side, in which case `whoami` looks fine but API commands fail.
+
+## Examples
+
+```bash
+canopy whoami
+```
+
+Prints your email, API URL, and token expiry for your default site — a quick sanity check before a deploy.
+
+```bash
+canopy --profile gcp-pilot whoami
+```
+
+Verifies you also hold a (non-expired) token for the GCP pilot site before targeting it.
+
+See also [canopy login](https://docs.canopy.website/cli/login) and [Sites & profiles](https://docs.canopy.website/platform/sites-and-profiles).

package/dist/docs/cli.md

@@ -0,0 +1,86 @@
+---
+title: CLI command reference
+description: Every canopy command, its flags, and what it does.
+---
+
+Run `canopy <command> --help` for the authoritative flags of any command. This
+is the one-page overview; the docs site's [CLI reference](https://docs.canopy.website/cli) section
+has a full page per command.
+
+## Auth
+
+- `canopy login` — sign in via OneLogin (opens the browser; finish there).
+  Add `--json` for machine-readable status output (for agents/CI).
+- `canopy whoami` — show the current login and token expiry.
+- `canopy logout` — forget the local CLI token.
+
+## Projects
+
+- `canopy create [name]` — register a **new** project (and scaffold it).
+  - `--slug <slug>` — URL slug (defaults to a slugified name).
+  - `--template <id>` — `static` | `spa` | `worker` (picker when omitted).
+  - `--scaffold` — write `./<slug>/` from the starter template (on by default;
+    `--no-scaffold` to only register).
+- `canopy init [slug] [dir]` — set up a local folder for an **existing** project
+  (e.g. one created in the dashboard) — does **not** register a new project.
+  - `dir` — `.` for the current directory, a path, or `./<slug>/` when omitted.
+  - `--template <id>` — template to scaffold (picker when omitted).
+  - `--no-scaffold` — link an app you already have: just write a `canopy.json`.
+- `canopy projects` — list your projects. `--all` includes ones you can't edit.
+- `canopy delete [slug]` — full teardown of a project. `--yes` skips the
+  type-the-slug confirmation.
+
+## Develop
+
+- `canopy dev` — run the project locally against live platform data.
+  - `--port <port>` — dev server port.
+  - `--local` — offline sandbox (PGlite + filesystem blobs under `.canopy/local/`).
+  - `--pull` — hydrate the sandbox from a fresh prod export first (with `--local`).
+
+## Deploy
+
+- `canopy deploy` — build and deploy the project (the `canopy.json` build
+  command runs first by default).
+  - `--no-build` — skip the build, deploy the output directory as-is.
+  - `--project <slug>` — deploy any directory, overriding (or without) a
+    `canopy.json`.
+- `canopy rollback [version]` — make an earlier deploy live again, e.g. `v3`
+  (picked from history when omitted). `--dir <path>` to target another directory.
+- `canopy download [version]` — download a deploy's assets as a zip, e.g. `v3`
+  (the live version when omitted, or picked from history interactively).
+  `--out <file>` to name it.
+- `canopy open` — open the deployed project in your browser.
+
+## Data
+
+- `canopy db pull` — download a fresh SQL dump. `--out <file>` to name it.
+- `canopy db snapshot` — store a dump server-side (restorable anytime).
+- `canopy db snapshots` — list stored snapshots.
+- `canopy db restore [file]` — replace ALL project data from a `.sql` file or
+  `--snapshot <key>`. `--yes` skips the confirmation. **Destructive.**
+- `canopy usage` — AI spend and storage for the project (same data as the
+  dashboard Usage tab). `--project <slug>` / `--json` for agents.
+
+## CI / deploy tokens
+
+- `canopy token create` — create a project-scoped deploy token for CI.
+  `--name "<label>"` to label it.
+- `canopy token list` — list the project's deploy tokens.
+- `canopy token revoke <id>` — revoke a token.
+
+See `canopy docs ci` for wiring push-to-main deploys.
+
+## Outbound hosts (egress)
+
+- `canopy egress list` — hosts the project's worker may `fetch` directly.
+- `canopy egress allow <host>` — allow a hostname (or `"*.sub.wildcard"`).
+- `canopy egress remove <host>` — remove an entry.
+
+## Maintenance
+
+- `canopy upgrade` — update the CLI to the latest version. `--version <v>` pins a
+  release; `--pm <npm|pnpm|yarn|bun>` overrides the package-manager guess.
+  Upgrading also refreshes the installed Canopy agent skill.
+- `canopy docs [topic]` — list docs, or print one. `--refresh` re-fetches from
+  the platform.
+- `canopy skill install` — (re)install the Canopy agent skill into this repo.

package/dist/docs/data.md

@@ -0,0 +1,85 @@
+---
+title: Working with project data
+description: Pulling, snapshotting, and restoring your project database.
+---
+
+Each Canopy project gets its own database and blob storage (D1 and R2 on the
+Cloudflare target; Postgres and GCS on GCP). Your app reads and writes them
+through the Canopy SDK at runtime; the CLI gives you tools to manage the data
+around it.
+
+## Collections in your app (SDK)
+
+The paved road is document-style collections:
+
+```ts
+await canopy.db.collection("blog_posts").insert({ title: "Hello" });
+```
+
+**Collection names must be lowercase** — start with a letter, then letters,
+digits, and underscores only (`^[a-z][a-z0-9_]*$`). `blog_posts` is fine;
+`blogPosts` or `BlogPosts` are **not** and throw at runtime:
+
+> `Invalid collection name "BlogPosts" — use lowercase letters, digits and underscores.`
+
+Use `snake_case` for multi-word names. This mirrors the collection name straight
+into the underlying database, so keeping it lowercase avoids case-sensitivity
+surprises.
+
+## Dialects and raw SQL
+
+The document API above is portable — it behaves the same on every platform
+target. Raw SQL is not: `canopy.db.sql()` passes your statement through
+untranslated, so it speaks whatever the target's database speaks. Ask the
+platform which that is:
+
+```ts
+await canopy.db.dialect(); // "sqlite" | "postgres"
+```
+
+Parameterize with `?` on sqlite and `$1` on postgres. One more per-target
+difference: `collection().search()` is real full-text search (FTS5) on sqlite
+targets, and a plain substring match on postgres targets — different matches,
+no ranking.
+
+## Download a dump
+
+```bash
+canopy db pull                 # writes <slug>-<timestamp>.sql
+canopy db pull --out data.sql  # choose the filename
+```
+
+A plain SQL dump you can inspect, diff, or keep as a backup.
+
+## Snapshots (server-side backups)
+
+```bash
+canopy db snapshot     # store a dump on the platform
+canopy db snapshots    # list stored snapshots
+```
+
+Snapshots live on the platform and can be restored at any time — handy before a
+risky change.
+
+## Restore — destructive
+
+> **Warning:** Restoring **replaces ALL project data**. Take a snapshot first — a snapshot taken seconds earlier
+> is your undo button.
+
+Restore from either source:
+
+```bash
+canopy db restore backup.sql          # from a local dump
+canopy db restore --snapshot <key>    # from a server-side snapshot
+```
+
+You'll be asked to type the project slug to confirm. `--yes` skips that prompt —
+use it only in scripts you trust.
+
+## Safe workflow for agents
+
+Before any destructive data change:
+
+1. `canopy db snapshot` — take a restore point.
+2. Make the change (or test it first with `canopy dev --local --pull`).
+3. If something goes wrong, `canopy db restore --snapshot <key>`.

package/dist/docs/deploy.md

@@ -0,0 +1,81 @@
+---
+title: Deploying a project
+description: How canopy deploy builds, uploads, and makes a version live.
+---
+
+From inside a project directory:
+
+```bash
+canopy deploy
+```
+
+This uploads your built assets to the platform, creates a new immutable deploy
+version, and makes it live. Each deploy is versioned (`v1`, `v2`, …).
+
+Under the hood a deploy is three steps: the platform authorizes it and issues a
+short-lived signed upload grant, the CLI uploads each file directly against
+that grant, and a completion call checks the bundle and makes the new version
+live. You only ever run `canopy deploy` — but it means a half-uploaded deploy
+is never served.
+
+## Building first
+
+If your project needs a build step (React SPA, anything with a bundler), declare
+the build command in `canopy.json` — `canopy deploy` runs it automatically
+before uploading. To skip the build and upload whatever is already in the
+output directory (or the static files as-is for a `static` project):
+
+```bash
+canopy deploy --no-build
+```
+
+## Trying it on staging first
+
+Nervous about a change — especially one with schema migrations or backend
+code? Deploy it to the project's staging channel first, then promote the exact
+same version once it checks out:
+
+```bash
+canopy deploy --staging   # own URL, own database (a copy of live)
+canopy promote            # make that version live
+```
+
+See [Staging & promoting](https://docs.canopy.website/guides/staging).
+
+## Rolling back
+
+Every deploy is kept, so you can instantly revert:
+
+```bash
+canopy rollback          # pick a version from history
+canopy rollback v3       # make v3 live again
+```
+
+Rollback re-points the live version at an existing deploy — it does not
+rebuild, and the project's backend rolls back with it.
+
+## Downloading a version
+
+Every version's assets can be pulled back down as a zip — the exact files that
+were deployed, for any version in the history:
+
+```bash
+canopy download          # the live version (pick from history in a terminal)
+canopy download v3       # a specific version
+canopy download v3 --out release.zip
+```
+
+The same download is available per version from the dashboard (project overview
+→ Deploys). Handy for archiving a release or moving a matured project off the
+platform.
+
+## Seeing the live site
+
+```bash
+canopy open
+```
+
+## Deploying from CI
+
+For automated push-to-main deploys, use a deploy token instead of an interactive
+login — see `canopy docs ci`.

package/dist/docs/dev.md

@@ -0,0 +1,72 @@
+---
+title: Local development
+description: Running a project locally against live or sandboxed data.
+---
+
+From inside a project directory:
+
+```bash
+canopy dev
+```
+
+By default `canopy dev` runs your project locally but talks to **live platform
+data** (your project's real database, blobs, and AI). This is the fastest way to
+develop against realistic state.
+
+- `--port <port>` — choose the dev-server port.
+
+## Offline sandbox
+
+To develop without touching live data — for example on a plane, or before you
+trust a destructive change — use a local sandbox backed by an embedded database
+and a filesystem blob store:
+
+```bash
+canopy dev --local
+```
+
+This creates a local database and blobs under `.canopy/local/` in your
+project. The sandbox starts empty.
+
+To seed the sandbox from a fresh copy of production data first:
+
+```bash
+canopy dev --local --pull
+```
+
+`.canopy/local/` is disposable — delete it to reset the sandbox.
+
+By default the sandbox runs PGlite (embedded Postgres), so raw
+`canopy.db.sql()` speaks the postgres dialect there, while your deployed
+project speaks whatever its platform target speaks (`canopy.db.dialect()`
+tells you — sqlite on Cloudflare). Collections (`canopy.db.collection(...)`)
+behave the same in both, so this only matters for hand-written SQL — see
+`canopy docs data`. If your project's raw SQL targets a sqlite site, lock the
+dialect in `canopy.json` (`"dialect": "sqlite"`) and the sandbox runs an
+embedded SQLite engine instead, so the same SQL works locally and deployed —
+see [canopy dev](https://docs.canopy.website/cli/dev).
+
+## Backend worker
+
+Projects with a `worker` entry in `canopy.json` get their backend locally too:
+`/api/*` is served by your worker in both modes, with the same `env` it has in
+production (`env.CANOPY`, `env.DB`, `env.BLOB`, `env.USER`). Edit and refresh —
+there's no build step.
+
+Secrets are the one thing that doesn't come from the dashboard. Stored values
+are never downloadable, so put local ones in a `.dev.vars` file next to
+`canopy.json`:
+
+```
+STRIPE_KEY=sk_test_local
+```
+
+Your worker reads them the same way it reads dashboard secrets
+(`c.env.STRIPE_KEY`). `canopy dev` prints which dashboard secret names your
+`.dev.vars` is missing. Keep the file out of git — the scaffolds ignore it.
+
+## Which mode should an agent use?
+
+- Iterating on UI or read-only features → `canopy dev` (live data, realistic).
+- Testing writes, migrations, or anything destructive → `canopy dev --local`
+  (optionally `--pull` to start from real data).

package/dist/docs/developers-agents-and-ai.md

@@ -0,0 +1,95 @@
+---
+title: Building with agents
+description: Teach your coding agent Canopy — the agent skill, offline docs, template guardrails, and prompts that work.
+---
+
+Canopy is built to be driven by coding agents. Three pieces make that work:
+an installable agent skill, docs the CLI carries offline, and guardrail files
+every new project ships with. Set them up once and your agent knows how to
+scaffold, run, deploy, and manage data without guessing.
+
+## Install the skill
+
+From your project (or any repo the agent works in):
+
+```bash
+canopy skill install
+```
+
+This writes the skill to the tool-neutral `.agents/skills/canopy/` tree and
+symlinks `.claude/skills/canopy` to it, so Claude Code picks it up while other
+agents read `.agents/`. `canopy upgrade` refreshes it alongside the CLI.
+
+The skill teaches an agent to:
+
+- **Check install and login first** — `canopy --version`, `canopy whoami`,
+  and how to run `canopy login` correctly (hand the browser sign-in to the
+  human; never touch credentials).
+- **Read docs before acting** — prefer `canopy docs <topic>` and
+  `canopy <command> --help` over guessing flags.
+- **Choose the right starter** — `spa` for anything real (typed SDK),
+  `static` only for trivial pages, `worker` when server-side code is needed —
+  and use `canopy init <slug>` (never `canopy create`) for a project that
+  already exists.
+- **Respect safety rules** — confirm before deploys, snapshot before
+  `canopy db restore`, treat `canopy delete` as destructive.
+
+## Offline docs for agents
+
+The CLI ships the full platform documentation and keeps it fresh from the
+platform, so an agent can read it without a browser — even before signing in:
+
+```bash
+canopy docs            # list all topics
+canopy docs deploy     # print one topic
+canopy docs cli --refresh   # force a re-fetch from the platform
+```
+
+Topics mirror the [guides](https://docs.canopy.website/guides/getting-started) on this site:
+`getting-started`, `cli`, `dev`, `deploy`, `data`, `ci`, `troubleshooting`,
+and more.
+
+## Template guardrails
+
+Every scaffolded project includes an `AGENTS.md` (the agent-facing README)
+that encodes the platform's boundaries, so an agent starting cold in the repo
+already knows the rules:
+
+- **Don't add auth** — the platform authenticates every request first.
+- **Don't store secrets** in the repo or browser code; set them in the
+  dashboard, and only a backend worker reads them.
+- **No SSR, no custom servers, no external databases** — data goes through
+  `canopy.db` and `canopy.blob`.
+- `canopy dev` uses **live** project data: snapshot before risky writes, or
+  use `canopy dev --local` for an offline sandbox where writes never reach
+  the platform.
+
+## Prompts that work
+
+With the skill installed, these are safe, copy-pasteable asks — each maps to
+commands the skill and docs actually cover:
+
+```text
+Set up Canopy in this repo: check the CLI is installed and I'm logged in,
+then install the Canopy skill and skim `canopy docs getting-started`.
+```
+
+```text
+Create a new Canopy project for a team lunch-voting app (spa template),
+run it locally with `canopy dev`, and build the first version of the UI.
+```
+
+```text
+Deploy this project to Canopy, then open the live site so I can check it.
+If anything looks wrong, roll back to the previous version.
+```
+
+```text
+Take a database snapshot, then pull the production data with
+`canopy db pull` and use the dump to reproduce the bug locally with
+`canopy dev --local --pull`.
+```
+
+> **Note:** Deploys go live behind company sign-in and restores replace all project data — a well-behaved
+> agent will confirm both with you first. That caution comes from the skill; keep it installed and
+> current.

package/dist/docs/developers-architecture.md

@@ -0,0 +1,106 @@
+---
+title: How the platform serves your project
+description: What happens between a browser and your deployed code — auth wall, static assets, the optional backend worker, and where data lives.
+---
+
+You never manage servers on Canopy, but it helps to know what the platform
+does with a request. This page covers the pieces a project developer actually
+touches; platform internals stay out of it.
+
+## The request path
+
+Every project lives at `https://<slug>.canopy.<domain>`. Requests hit the
+**gateway** first, which enforces authentication before any of your project's
+bytes are served — then either serves your deployed static files or, if the
+project has one, dispatches `/api/*` to your backend worker.
+
+```mermaid
+flowchart TD
+    B[Browser] --> G["Gateway<br/>auth wall: OneLogin session<br/>or client password"]
+    G -->|"most paths"| A["Static assets<br/>deployed build, SPA fallback"]
+    G -->|"/api/*"| W["Backend worker<br/>(optional, canopy.json 'worker')"]
+    G -->|"/_api/data/v1/*"| P["Platform data plane<br/>auth · db · blob · ai"]
+    W --> P
+    P --> D[("Project database<br/>+ blob prefix")]
+```
+
+## The auth wall
+
+Authentication is a platform property — your app cannot opt out, and must not
+build its own. A visitor without a valid session is redirected into the
+OneLogin sign-in flow; on projects with client access enabled, outsiders get a
+password page and receive a scope-limited `external` session instead. Only
+after that does any project code or asset get served. Your app just asks
+`canopy.auth.user()` who came through the door
+(see the [SDK reference](https://docs.canopy.website/sdk)).
+
+## Static assets and the SPA fallback
+
+A deploy uploads your built files as an immutable, numbered version; serving
+reads whichever version is live. Requests for paths that don't match a file
+fall back to `index.html`, so client-side routes like `/settings` work on a
+hard refresh without any configuration. Rollback just repoints "live" at an
+earlier version — instant, nothing rebuilt.
+
+The full path — including caching, version-pinned `v12-dot-<slug>` preview
+hosts, and the security review — is in
+[How static files are served](https://docs.canopy.website/guides/static-serving).
+
+## The optional backend worker
+
+Most projects are frontend-only: the SDK talks straight to the platform, and
+no server code exists. When you need server-side code — say, calling an
+external API with a secret the browser can't hold — the `worker` template adds
+a backend, declared in `canopy.json`:
+
+```json
+{
+  "slug": "my-app",
+  "build": "npm run build",
+  "dist": "dist",
+  "worker": "worker/index.ts"
+}
+```
+
+Requests under `/api/*` reach the worker (Hono-style handlers); everything
+else is still static serving. Three things to know:
+
+- **Requests arrive authenticated.** The worker sits behind the same gateway
+  wall as the frontend.
+- **Platform access goes through the same SDK**, via the `CANOPY` service
+  binding — same budgets, same data isolation as the browser:
+
+  ```ts
+  app.get("/api/hello", async (c) => {
+    const canopy = createCanopy({ fetch: c.env.CANOPY.fetch.bind(c.env.CANOPY) });
+    const user = await canopy.auth.user();
+    return c.json({ message: `Hello, ${user.name}!` });
+  });
+  ```
+
+- **Secrets and schedules come from the dashboard.** Secrets (Settings →
+  Secrets) land as Workers-shaped bindings (`c.env.MY_API_KEY`, not
+  `process.env`); dashboard Schedules invoke an exported
+  `scheduled(event, env)` — switch on `event.name`.
+
+> **Warning:** Backend workers are capability-gated per target: today the GCP target runs them, while on
+> Cloudflare sites a worker deploy answers a clear "not supported yet". Frontend-only projects
+> deploy everywhere.
+
+## Where your data lives
+
+Every project gets its own database and its own blob-storage prefix. No other
+project can read them, and deleting the project tears everything down. The
+document API is portable across targets; raw SQL speaks the target's dialect
+(`sqlite` or `postgres` — ask `canopy.db.dialect()`). Dumps, snapshots, and
+restores are CLI commands — see the [project data guide](https://docs.canopy.website/guides/data).
+
+## Sites
+
+A _site_ is one installation of the whole platform. The CLI ships three
+profiles — `main` (canopy.website, Cloudflare), `staging` (thanarie.dev,
+Cloudflare), and `gcp-pilot` (canopy.monks.zone, GCP) — and always shows which
+one you're on. Projects pin theirs in `canopy.json`; `--profile` or
+`CANOPY_PROFILE` overrides per command. Most projects only ever use `main`.
+Target differences (dialect, full-text search, worker support) surface as
+capabilities, not separate APIs.

package/dist/docs/getting-started.md

@@ -0,0 +1,108 @@
+---
+title: Getting started
+description: Install the CLI, sign in with OneLogin, and ship your first project.
+---
+
+Canopy is Monks' managed platform for vibecoded projects. You build a small web
+app, and Canopy hosts it, gives it a database, blob storage, and AI — no
+infrastructure to manage.
+
+This guide is written so an AI coding agent (Claude, Cursor, etc.) can follow it
+on your behalf. Everything runs through one command-line tool: `canopy`.
+
+## 1. Install the CLI
+
+The CLI is published on npm. Install it globally:
+
+```bash
+npm install -g @mediamonks/canopy-cli
+```
+
+Confirm it's on your PATH:
+
+```bash
+canopy --version
+```
+
+If `npm` isn't available, install Node.js 20+ first (https://nodejs.org), then
+re-run the install.
+
+## 2. Sign in
+
+Canopy authenticates through Monks' OneLogin. Run:
+
+```bash
+canopy login
+```
+
+This opens your browser. **Finish the sign-in there** — the CLI waits for the
+browser to redirect back, then stores a token in `~/.canopy/config.json`.
+
+> If you are an agent: run `canopy login`, then stop and tell the human to
+> complete the sign-in in the browser window that just opened. Never ask for or
+> type the user's password or any codes yourself.
+
+Check who you are at any time:
+
+```bash
+canopy whoami
+```
+
+## 3. Create your first project
+
+```bash
+canopy create
+```
+
+This prompts for a name and a starter template, scaffolds a runnable project
+directory, and registers the project on the platform. To skip the prompts:
+
+```bash
+canopy create "My App" --scaffold --template spa
+```
+
+> If you are an agent: don't stop at printing this command. Ask the person what
+> they'd like to build and what it's about, then pick a name and template for
+> them and run `canopy create` non-interactively — then keep going and build
+> it. Aim for a working first project, not a list of commands.
+
+Templates: **`static`** (no-build html/css/js; SDK served untyped from the
+platform) is the default and fine for a trivial page or two. Reach for
+**`spa`** (Vite + React + TypeScript; typed SDK from npm) once you lean on the
+SDK or expect the app to grow — most projects want this.
+
+## 4. Run it locally
+
+```bash
+cd my-app
+canopy dev
+```
+
+Your project runs against live platform data by default. For an offline sandbox
+with local data, use `canopy dev --local`.
+
+## 5. Deploy
+
+```bash
+canopy deploy
+```
+
+Then open the live site:
+
+```bash
+canopy open
+```
+
+## Where to go next
+
+Everything the CLI can do is documented and available offline. List the topics:
+
+```bash
+canopy docs
+```
+
+Read one, e.g.:
+
+```bash
+canopy docs deploy
+```