ghostdock 0.0.7 → 0.0.9

package/dist/cli.md

@@ -0,0 +1,733 @@
+# Ghostdock CLI
+
+Command-line access to your Ghostdock account — built for agents, but usable by humans too.
+Authenticate once, then call Ghostdock's tools without leaving the terminal.
+
+This document is written for an agent (or human) driving the CLI directly. It is also published at
+`https://ghostdock.brainchimps.com/cli.md` so an agent can `curl`/fetch it without cloning this repo.
+
+## Install / run
+
+No install required — run it with `npx`:
+
+```bash
+npx ghostdock --help
+```
+
+Or install it globally:
+
+```bash
+npm install -g ghostdock
+ghostdock --help
+```
+
+A global install also gives you `gdock`, a short name for the same CLI. Help
+and hints use whichever name you typed. With `npx`, use `npx ghostdock`:
+`npx gdock` does not work.
+
+Inside this monorepo (for development), run from the repo root or `packages/cli`:
+
+```bash
+bun run --cwd packages/cli build   # bundles src/index.ts -> dist/index.js
+bun run --cwd packages/cli dev -- --help  # run from source without building
+```
+
+## Output: for people, and `--json` for scripts and agents
+
+Every command prints for people by default: one line per event, a symbol, then the message.
+
+```
+$ ghostdock sandboxes list
+  ⚓ Marketing site  quiet-harbor  running
+  ◌ teal-jetty  stopped
+$ ghostdock sites publish ./dist
+  ↗ https://foggy-teal-bollard.static.ghostdock.app
+  ✓ Published site foggy-teal-bollard.
+```
+
+`⚓` ready, `✓` done, `↗` a URL, `◌` stopped or gone, `✗` failed, `▂▄▆` in progress. Every line
+carries the name and id the next command needs.
+
+Commands that wait show a progress line on stderr while they run. Starting a sandbox
+(`sandboxes create`, `sandboxes wake`) prints how long each step took, measured on the server, each
+step with its own time:
+
+```
+$ ghostdock sandboxes wake quiet-harbor
+  ⚓ quiet-harbor  running
+  ⚓ sandbox started in 125ms
+  ✓ container started in 3.0s
+```
+
+The container line is missing when no container was started, or when the host is older and did
+not report it. `sandboxes status` prints the same lines for the last start. With `--json` they are
+the `boot` field: `{ trigger, sandbox: { startedAt, readyAt, ms }, container: { … } | null }`, or
+`null` when the command started nothing.
+
+**Scripts and agents pass `--json`.** It prints the result as one JSON document on stdout, with
+every field, and nothing else there. It works on every command and anywhere on the line:
+
+```bash
+ghostdock sandboxes list --json | jq -r '.sandboxes[].name'
+```
+
+- **stdout is the result, stderr is everything else**: notices (`Using organization acme …`),
+  hints and errors. Piping stdout never picks up a notice.
+- **Errors** print as `✗ <what went wrong and what to try>` on stderr and exit non-zero, with or
+  without `--json`.
+- **Colour** only on a terminal: piped output and `NO_COLOR=1` get the same text without colour
+  codes. `FORCE_COLOR=1` turns it back on.
+
+## Global flags
+
+```
+ghostdock --version
+ghostdock --base-url <url> <command>
+ghostdock <command> --json
+```
+
+- `--version` / `-v` — print CLI version and exit
+- `--base-url <url>` — API origin for this invocation (wins over `GHOSTDOCK_BASE_URL`)
+- `--json` — print the result as one JSON document on stdout (see Output above)
+
+## Commands
+
+Commands are grouped by resource, like `gh` or `kubectl`: `ghostdock <resource> <action>`.
+
+<!-- generated:command-groups:start (bun run sync:cli-reference; do not edit) -->
+```
+ghostdock apps            Published apps of an organization.
+ghostdock env             Manage organization environment variables and secrets.
+ghostdock images          Organization image catalog: OCI bookmarks, Dockerfiles and Compose files.
+ghostdock login           Sign in and store a device access token for this CLI.
+ghostdock logout          Revoke the device session and remove stored credentials.
+ghostdock network         The private network: reach your sandboxes by address and name from this machine.
+ghostdock organizations   Organizations you belong to.
+ghostdock projects        Deployable projects, their deployments and environment.
+ghostdock providers       Sandbox providers of an organization.
+ghostdock registry        Log in to the organization container registry.
+ghostdock sandboxes       Create, run and manage sandboxes.
+ghostdock sites           Static sites on the CDN.
+ghostdock skills          List and read Agent Skills (same catalog as MCP skill://index.json).
+ghostdock snapshots       Sandbox snapshots.
+ghostdock tools           List available agent tools.
+ghostdock whoami          Show the account this CLI is currently authenticated as.
+```
+<!-- generated:command-groups:end -->
+
+Run `ghostdock <command> --help` at any level for its subcommands or flags, e.g.
+`ghostdock sandboxes --help` or `ghostdock sandboxes urls create --help`.
+
+Most commands are generated from the tool catalog — see **Invoking a tool** below. Every command
+is listed in the [command index](#command-index); [`cli-reference.md`](cli-reference.md) has each
+one's full description and flags.
+
+### Choosing an organization
+
+Every organization-scoped command acts on one organization, taken from the first of:
+
+1. `--org <id-or-slug>` on the command
+2. the `GHOSTDOCK_ORG` environment variable
+3. the default set with `ghostdock organizations use <id-or-slug>`
+
+```bash
+ghostdock organizations use acme      # default for this directory (login sets one when it can)
+ghostdock sandboxes list              # stderr: Using organization acme (default, …)
+ghostdock sandboxes list --org beta   # --org always wins
+ghostdock organizations current       # which organization, and where it comes from
+ghostdock organizations use --clear
+```
+
+When the organization does not come from `--org`, the command says which one it uses on stderr,
+so a default never acts silently. The default is stored next to the credentials
+(`./.ghostdock/settings.json`), so it belongs to that directory's login. **Scripts and CI should
+pass `--org` or set `GHOSTDOCK_ORG`** rather than depend on (or change) a stored default, and use
+the organization id: renaming an organization changes its slug, not its id.
+
+### `ghostdock login`
+
+Ghostdock uses a device-authorization flow: no password is ever typed into the terminal.
+
+**Default (print-and-exit) — best when a human is present to click the link:**
+
+```bash
+ghostdock login
+```
+
+This prints a URL to open in a browser and exits `0` immediately — it does not prompt for input or
+poll for approval. Approve the request in the browser, then complete login with
+**`ghostdock login --code <paste-code>`**, redeeming the one-time code from the browser's
+"Having trouble? Show code" link (see below).
+
+Each `login` invocation starts a **new** device session. A later `login --wait` does **not** resume
+polling for a prior plain `login`. To block until approval, run **`ghostdock login --wait` up
+front** instead of plain `login`.
+
+**`--wait` — poll until approved:**
+
+```bash
+ghostdock login --wait
+# or with a custom timeout (seconds, default 300):
+ghostdock login --wait --timeout 120
+```
+
+Prints the same URL, then polls the server every few seconds until the login is approved, denied,
+or the timeout elapses. Exits `0` on success, non-zero otherwise.
+
+**`--code` — paste-code fallback:**
+
+If the CLI can't poll (e.g. it's running in a sandbox with no long-lived process, or the browser
+approval happened on a different machine), the browser's "Having trouble? Show code" link reveals a
+short one-time code. Redeem it directly:
+
+```bash
+ghostdock login --code <paste-code>
+```
+
+On success, credentials are written and the command exits `0`. If the code hasn't been approved
+yet, it exits `1` — approve it in the browser first.
+
+**Default organization after login.** Once logged in (with `--wait` or `--code`), `login` sets the
+default organization when that is unambiguous:
+
+- `--org <id-or-slug>` sets that one, e.g. `ghostdock login --wait --org acme`. If you are not a
+  member of it, no default is set and `login` exits `1`.
+- A default that is still one of your organizations stays as it is.
+- With exactly one organization, that one becomes the default.
+- With several, a person at a terminal picks one from a numbered list (Enter skips). Without a
+  terminal (agents, CI) nothing is asked: `login` lists them and points to
+  `ghostdock organizations use`.
+
+See [Choosing an organization](#choosing-an-organization) for how commands pick it up.
+
+### `ghostdock logout`
+
+```bash
+ghostdock logout
+```
+
+Revokes the device session on the server (best-effort — still clears local credentials even if the
+server call fails, e.g. when offline) and deletes the local credentials file.
+
+### `ghostdock whoami`
+
+```bash
+ghostdock whoami
+```
+
+Prints who the stored access token belongs to and which server it talks to (`--json`:
+`{ "userId": ..., "baseUrl": ... }`).
+Transparently refreshes an expired access token using the stored refresh token before failing.
+Exits `1` with a message if not logged in or the session can't be refreshed.
+
+### `ghostdock tools`
+
+Lists the tool catalog for the authenticated account:
+
+```bash
+ghostdock tools          # name + description, one per line
+ghostdock tools --json   # the full catalog (including each tool's JSON Schema) as JSON
+```
+
+Requires login — prints a hint and exits `1` if there's no valid session.
+
+### `ghostdock skills`
+
+Lists and reads **Agent Skills** for the authenticated account — the same catalog MCP
+clients discover at `skill://index.json` (SEP-2640 / Agent Skills discovery 0.2.0).
+Prefer resources. The MCP tools `skills_list` and `skills_get` are fallbacks for clients that
+cannot use `resources/list` and `resources/read` — skip them if those work.
+
+```bash
+ghostdock skills list                          # name, description, and skill:// URI per skill
+ghostdock skills list --json                   # official discovery index ($schema + skills[])
+ghostdock skills get skill://github/SKILL.md   # print SKILL.md
+ghostdock skills get github                    # same, by name
+ghostdock skills get org_1/release-notes       # organization skill
+```
+
+`--json` on `get` prints `{ uri, name, description, markdown }`. If the same name exists
+in more than one organization, pass the `skill://` URI from the index.
+
+Requires login — prints a hint and exits `1` if there's no valid session.
+
+### Invoking a tool
+
+Every catalog tool is a command at its own path, with one `--flag` per schema property
+(`sandboxProviderId` -> `--sandbox-provider-id`). The one thing a command acts on is positional instead:
+`ghostdock sandboxes stop <sandbox-id>`, `ghostdock sandboxes urls delete <url-id>`,
+`ghostdock env get <name>`. The organization is always the `--org` flag, by id or slug: a slug is easier to type, an id keeps
+working after the organization is renamed (renaming changes the slug). The MCP tool name is the same path joined with
+underscores: `ghostdock sandboxes urls create` calls the `sandboxes_urls_create` tool. Run
+`ghostdock <command> --help` to see a command's full description, its flags and which are
+required; a group's `--help` lists its commands with one line each. Output is a line per item
+for people; `--json` prints the tool's result as it comes back over MCP.
+
+```bash
+ghostdock organizations list
+#   • Acme  org_123
+ghostdock organizations list --json
+# {"organizations": [{"id": "org_123", "name": "Acme", "slug": "acme"}]}
+```
+
+Number/boolean flags are parsed from their string form; array/object flags take a raw JSON string
+(e.g. `--tags '["a","b"]'`). Requires login — prints a hint and exits `1` if there's no valid
+session, or the server's error message (e.g. "Not a member of this organization") on a `4xx`.
+
+The tool list embedded in the CLI binary is generated at build time from the server's tool catalog
+(`bun run sync-catalog` in `packages/cli`), so `--help` and flag parsing work offline; invoking a
+tool still requires a network call and a valid session.
+
+Command descriptions are short on purpose. Concepts and workflows live in the built-in Agent
+Skills, the same documents MCP agents read:
+
+```bash
+ghostdock skills get sandboxes      # sources, manifests, lifecycle, providers, URLs and TCP
+ghostdock skills get sandbox-boot   # processes that must come back after idle-stop
+ghostdock skills get environment    # organization entries, bindings, local entries, secrets
+ghostdock skills get publishing     # sites publish vs projects publish, outcomes, redeploys
+ghostdock skills get incus-setup    # connecting your own Incus host
+```
+
+### Sandboxes
+
+Read `ghostdock skills get sandboxes` before your first sandbox: what it can boot from, manifests,
+idle-stop and auto-delete, providers, URLs.
+
+Every sandbox has a name like `quiet-harbor`, unique within its organization, and every command
+that takes a sandbox accepts it with the organization (`--org`, `GHOSTDOCK_ORG` or the default).
+The long `sandboxId` in `--json` output works too, in the same organization. A name never changes
+while the sandbox exists, so scripts can keep it; once a sandbox is deleted, its name may be given to
+a new one later. The display name is a separate label you can edit. For example, create a sandbox,
+then expose a URL:
+
+```bash
+ghostdock sandboxes create --org org_123 --display-name "Marketing site"
+ghostdock sandboxes urls create quiet-harbor --port 8080 --auto-wake true --public true
+```
+
+#### Environment in a sandbox
+
+A sandbox exports **nothing** by default (unless you boot from an organization snapshot or catalog
+image whose manifest supplies defaults). `environment` has three parts: `organization` (plain same-name opt-ins from the
+catalogue, see [`ghostdock env`](#ghostdock-env)), `bindings` (slot ← org entry remaps), and `local` (sandbox-only variables/secrets). A local entry overrides an
+organization export of the same name. Prefer the CLI when setting secret values so they are not
+pasted into the agent conversation.
+
+```bash
+# At create time, in one call:
+ghostdock sandboxes create --org org_123 \
+  --environment '{"organization":["VITE_API_URL","BUILD_TOKEN"],"bindings":[{"name":"DATABASE_URL","organization":"PROD_DATABASE_URL"}],"local":[{"name":"API_KEY","value":"sk_live","kind":"secret"}]}'
+
+# Afterwards:
+ghostdock sandboxes env get quiet-harbor
+ghostdock sandboxes env select quiet-harbor --environment '["VITE_API_URL"]' \
+  --bindings '[{"name":"DATABASE_URL","organization":"PROD_DATABASE_URL"}]'
+ghostdock sandboxes env select quiet-harbor --environment '[]'   # clears plain + remaps (omit bindings)
+ghostdock sandboxes env set API_KEY --sandbox-id quiet-harbor --value sk_live --kind secret
+ghostdock sandboxes env delete API_KEY --sandbox-id quiet-harbor
+```
+
+Values arrive as real environment variables, so read them with `process.env` / `$VAR` inside the
+sandbox. **Do not pass secrets in `sandboxes commands run` strings** — the command text is retained and
+readable through `sandboxes commands logs`. `sandboxes env get` reports every organization entry
+(selected + overriddenByLocal) and the sandbox's own local entries; `sandboxes status` reports
+just the resolved names.
+
+New shell commands and SSH sessions see a change immediately. Processes already running keep the
+values they booted with until restarted (pass `--restart` to `sandboxes env select` /
+`sandboxes env set` / `sandboxes env delete` to restart a running sandbox
+instead).
+
+### Images
+
+Organization image catalog: OCI bookmarks (`images add`), stored Dockerfiles
+(`images add-dockerfile`), and refs currently in use on sandboxes. `images list` and `images get`
+cover the same catalog family as those add tools — each org row includes `kind`, a redacted
+`manifest` (from `ghostdock.*` Docker/OCI labels), `requiredEnvironment`, and `requiredUrls` (same
+shape as snapshots). `sandboxes create` with `--source '{"type":"image","id":"..."}'` boots a catalog
+row by id and applies its manifest (URLs + env) like an organization snapshot.
+
+```bash
+ghostdock images list --org org_123
+ghostdock images get img_abc --org org_123
+ghostdock images add --org org_123 --ref ghcr.io/acme/app:latest --label "Acme app"
+ghostdock images add-dockerfile --org org_123 --name my-stack --dockerfile "$(cat Dockerfile)"
+ghostdock sandboxes create --org org_123 \
+  --source '{"type":"image","id":"img_abc"}' \
+  --environment '{"local":[{"name":"API_KEY","kind":"secret","value":"sk_test"}]}'
+```
+
+Booting with `--source '{"type":"dockerfile","content":"..."}'` parses labels inline without
+persisting a catalog row. That JSON source is Dockerfile text only: COPY/ADD of local files fails.
+`--source '{"type":"compose","files":{"compose.yaml":"..."}}'` boots Docker-in-Docker from those
+inline files (must include `docker-compose.yml`/`yaml` or `compose.yml`/`yaml`) and runs
+`docker compose up`; `ghostdock.*` service labels become the create-time manifest. A directory or
+ZIP — Dockerfile build context, or a Compose project with extra files — is
+[`ghostdock sandboxes build`](#ghostdock-sandboxes-build), not this command. Any OCI ref may still
+be passed as `{ type: "image", ref }` even when it does not appear in `images list`. Catalog compose
+rows still boot via `{ type: "image", id }`.
+
+### `ghostdock sites publish`
+
+Publish a local directory or ZIP to the CDN (durable public URL, no sandbox):
+
+```bash
+ghostdock sites publish --org org_123 ./dist
+ghostdock sites publish --org org_123 --zip ./site.zip
+```
+
+MCP `sites publish` is for small inline payloads. Use this command for a real directory or large ZIP.
+
+### `ghostdock projects publish`
+
+Inspect a local source tree and publish (CDN when pre-built static, otherwise Compose from a DeploymentSpec).
+Required secrets without values return `awaiting_configuration` instead of a live URL.
+Re-invoke with `--environment` (same JSON shape as `sandboxes create`) after configuring.
+On `build_failed`, `start_failed`, or `verify_failed`, inspect the kept sandbox (unless verification tore it down), then re-invoke with `--spec` (JSON `DeploymentSpec`). The spec is executed on a fresh sandbox and stored for later replay. Do not pass `--spec` with `--replan`. Every terminal outcome stores the upload and returns authenticated `fileUrls`. Detected tests always run after the stack is up; pass `--require-verify` to refuse a deploy when they fail.
+
+```bash
+ghostdock projects publish --org org_123 ./app
+ghostdock projects publish --org org_123 --auto-stop-interval-minutes -1 --zip ./app.zip
+ghostdock projects publish --org org_123 --project-id proj_123 ./app
+ghostdock projects publish --org org_123 ./app \
+  --environment '{"organization":["DATABASE_URL"],"local":[{"name":"API_KEY","value":"sk_live","kind":"secret"}]}'
+ghostdock projects publish --org org_123 ./app --spec '{"version":1,"run":{"kind":"static","outputDir":"."},"env":[]}'
+ghostdock projects publish --org org_123 --require-verify ./app
+ghostdock projects publish --org org_123 --sandbox-provider-id prov_123 ./app
+```
+
+MCP `projects publish` is for small inline payloads. Use this command for a real directory or large ZIP.
+
+### `ghostdock sandboxes build`
+
+Create a sandbox from a local Dockerfile or Compose directory. The CLI zips the directory (or sends
+`--zip`) and the server builds it. MCP `sandboxes create` stays inline text only.
+
+```bash
+ghostdock sandboxes build --org org_123 --kind dockerfile ./app
+ghostdock sandboxes build --org org_123 --kind compose --zip ./stack.zip
+ghostdock sandboxes build --org org_123 --kind dockerfile \
+  --sandbox-provider-id prov_123 --display-name "API" ./app
+```
+
+The Dockerfile (`Dockerfile` or `dockerfile`) or a compose file (`docker-compose.yml`/`yaml`,
+`compose.yml`/`yaml`) must sit at the directory root, or at the root of the ZIP. A ZIP that wraps
+the project in one folder is unwrapped. Pass one directory or `--zip`, not both.
+
+### `ghostdock sandboxes files upload`
+
+`sandboxes files upload` is convenient for small payloads. For a local directory,
+multiple files, or a large ZIP, use the dedicated multipart upload command instead:
+
+```bash
+ghostdock sandboxes files upload quiet-harbor ./dist
+ghostdock sandboxes files upload quiet-harbor ./index.html ./assets
+ghostdock sandboxes files upload quiet-harbor --zip ./site.zip
+```
+
+Each positional path may be a file or directory. Directory contents are uploaded recursively,
+preserving their relative paths; a file is uploaded by its basename. A `sandboxes files upload` call needs
+at least one path or `--zip`. Uploading to a stopped sandbox resumes it automatically.
+
+### `ghostdock env`
+
+Manage the environment variables and secrets an organization offers to its sandboxes and projects.
+A sandbox inherits nothing automatically — select the entries it needs on that sandbox.
+
+```bash
+ghostdock env list --org org_123
+ghostdock env get VITE_API_URL --org org_123
+ghostdock env set VITE_API_URL --org org_123 --value https://api.example.com
+ghostdock env delete VITE_API_URL --org org_123
+```
+
+**Variables vs secrets.** A variable is readable by anyone who can see the organization; `env list`
+prints its value inline. A secret can be set and replaced but never read back — it shows as
+`<secret>` in `env list` and `env get` refuses it. Pass `--secret` to create one:
+
+```bash
+# Keeps the value out of shell history and the process list
+printf %s "$STRIPE_KEY" | ghostdock env set STRIPE_SECRET_KEY --org org_123 --secret --value-stdin
+```
+
+`--secret` is only required when creating; updating an existing entry keeps its kind. To convert one,
+pass `--kind variable` or `--kind secret` explicitly along with the new value:
+
+```bash
+ghostdock env set STRIPE_SECRET_KEY --org org_123 --kind variable --value not-secret-anymore
+# Warning: STRIPE_SECRET_KEY was a secret and is now a variable — its value is readable by everyone in the organization.
+```
+
+Converting never reveals the old secret: `set` always replaces the value, so the value you supply in
+that call is the one that becomes readable. The command prints what changed either way.
+
+`env get` prints the bare value so it can be captured in a shell (`API=$(ghostdock env get
+VITE_API_URL --org org_123)`). It also returns values too large for `env list`, which
+withholds anything over 1024 characters rather than truncating it — a printed value is always the
+complete value.
+
+With `--json`, `list`, `get` and `set` print the tool's result instead. These commands wrap the
+`env list`, `env get`, `env set` and
+`env delete` tools, which are also available directly (and over MCP).
+
+Names must be valid environment variable names, and names the sandbox runtime owns (`PATH`,
+`HOME`, anything starting with `GHOSTDOCK_`, …) are rejected. Prefix a name with `VITE_`
+only when browser code must read it: Vite inlines those into the published bundle, so a `VITE_`
+secret is public.
+
+### `ghostdock network`
+
+Reach your organization's sandboxes from this machine by private address and name, over
+WireGuard ([ADR 0027](../../docs/adr/0027-private-sandbox-network.md)). Everything on a
+sandbox's address is reachable: a container that publishes port 80 answers on
+`http://quiet-harbor.gdock.internal/`, as it would on `localhost` inside the sandbox.
+Nothing reaches your machine from a sandbox.
+
+```bash
+ghostdock network connect --org acme   # asks for sudo once: wg-quick up and split DNS
+ghostdock network ls --org acme        # sandboxes with their addresses and names
+curl http://quiet-harbor.acme.ghostdock.internal:8080/
+curl http://quiet-harbor.gdock.internal:8080/      # short name: the organization connect used
+ghostdock network use beta             # short names in another organization, no sudo
+ghostdock network status
+ghostdock network disconnect
+```
+
+- **Needs `wg-quick`** (`brew install wireguard-tools`, `apt install wireguard-tools`). macOS
+  and Linux. On Windows, run the CLI in WSL: then only tools inside WSL reach sandboxes.
+- **One key per machine**, kept in `~/.config/ghostdock/network/` (or `GHOSTDOCK_NETWORK_DIR`).
+  Only the public key is sent. The device belongs to the login it was connected with:
+  `ghostdock logout` takes it out of the network, and so does not connecting for 90 days.
+- **Names**: `<sandbox>.<org>.ghostdock.internal` always, and `<sandbox>.gdock.internal` in the
+  organization this machine is pinned to (the one `connect` resolved, changed with
+  `network use`). The pin is per machine, not per directory. Only AAAA records exist: the
+  network is IPv6, and the sandbox sees IPv4.
+- `ghostdock network devices` lists your devices, `ghostdock network devices remove <id>`
+  removes one.
+
+## Command index
+
+Every command with its arguments and what it does. Run `ghostdock <command> --help` for its flags,
+or read [`cli-reference.md`](cli-reference.md) for every command's full description and flags.
+
+<!-- generated:command-index:start (bun run sync:cli-reference; do not edit) -->
+#### apps
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock apps list [flags]` | List the live published apps (sites) of an organization, with their URLs. |
+
+#### env
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock env delete <name> [flags]` | Delete a variable or secret. |
+| `ghostdock env get <name> [flags]` | Print one variable value in full (secrets cannot be read). |
+| `ghostdock env list [flags]` | List variables and secrets. |
+| `ghostdock env set <name> [flags]` | Create or replace a variable or secret. |
+
+#### images
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock images add --ref <string> [flags]` | Bookmark an OCI image ref in the organization’s image catalog. |
+| `ghostdock images add-compose --name <string> --files <object> [flags]` | Add Compose files to the organization’s image catalog. |
+| `ghostdock images add-dockerfile --name <string> --dockerfile <string> [flags]` | Add a Dockerfile to the organization’s image catalog. |
+| `ghostdock images get <image-id> [flags]` | Get one catalog image with its spec, manifest and requirements. |
+| `ghostdock images list [flags]` | List the images an organization can boot sandboxes from. |
+| `ghostdock images remove <image-id> [flags]` | Remove an image from the organization’s catalog. |
+| `ghostdock images update-compose <image-id> [flags]` | Replace a catalog Compose image’s files and/or name. |
+| `ghostdock images update-dockerfile <image-id> --dockerfile <string> [flags]` | Replace a catalog Dockerfile, optionally renaming it. |
+
+#### login
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock login [flags]` | Sign in and store a device access token for this CLI. |
+
+#### logout
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock logout` | Revoke the device session and remove stored credentials. |
+
+#### network
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock network connect [flags]` | Put this machine into the private network: WireGuard and split DNS. |
+| `ghostdock network devices <command>` | Your devices in the private network. |
+| `ghostdock network devices remove <id>` | Remove one of your devices from the private network. |
+| `ghostdock network disconnect` | Take this machine out of the private network. |
+| `ghostdock network ls [flags]` | Sandboxes of an organization with their private addresses and names. |
+| `ghostdock network status` | Whether this machine is connected, and as which device. |
+| `ghostdock network use [org] [flags]` | Choose the organization <sandbox>.gdock.internal names resolve in on this… |
+
+#### organizations
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock organizations current [flags]` | Show which organization commands use, and where it comes from. |
+| `ghostdock organizations list` | List the organizations you belong to, with their ids and slugs. |
+| `ghostdock organizations use [org] [flags]` | Set the default organization for commands run in this directory. |
+
+#### projects
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock projects create --display-name <string> [flags]` | Create an empty project. |
+| `ghostdock projects deployments get <deployment-id> --project-id <string> [flags]` | Get one deploy attempt, with links to its stored files. |
+| `ghostdock projects deployments list <project-id> [flags]` | List a project’s deploy attempts, newest first. |
+| `ghostdock projects env delete <name> --project-id <string> [flags]` | Delete one of a project’s own variables or secrets. |
+| `ghostdock projects env get <project-id> [flags]` | Get a project’s stored environment. |
+| `ghostdock projects env select <project-id> --environment <array> [flags]` | Replace the organization entries a project exports. |
+| `ghostdock projects env set <name> --project-id <string> --value <string> --kind <string> [flags]` | Create or replace one of a project’s own variables or secrets. |
+| `ghostdock projects get <project-id> [flags]` | Get a project with its latest attempt and live deployment. |
+| `ghostdock projects list [flags]` | List an organization’s projects. |
+| `ghostdock projects publish [path] [flags]` | Inspect local source with the deploy agent and publish to the CDN or a sandbox. |
+| `ghostdock projects redeploy <project-id> [flags]` | Deploy a project’s stored source again, with its current environment. |
+| `ghostdock projects update <project-id> --display-name <string> [flags]` | Rename a project. |
+
+#### providers
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock providers disconnect <sandbox-provider-id> [flags]` | Disconnect one of the organization’s own sandbox providers. |
+| `ghostdock providers list [flags]` | List the sandbox providers an organization can create sandboxes on. |
+| `ghostdock providers rename <sandbox-provider-id> --name <string> [flags]` | Rename one of the organization’s own sandbox providers. |
+| `ghostdock providers set-default <sandbox-provider-id> [flags]` | Set the provider used when a create omits sandboxProviderId. |
+| `ghostdock providers start-incus [flags]` | Start connecting an Incus host as a sandbox provider. |
+| `ghostdock providers verify-incus <sandbox-provider-id> [flags]` | Check or finish connecting an Incus host. |
+
+#### registry
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock registry credentials [flags]` | Print registry host, username, and the one-hour password. |
+| `ghostdock registry login [flags]` | Fetch a one-hour password and run docker login --password-stdin. |
+
+#### sandboxes
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock sandboxes build [path] --kind <value> [flags]` | Create a sandbox from a local Dockerfile or Compose directory. |
+| `ghostdock sandboxes commands get <command-id> --sandbox-id <string> --session-id <string> [flags]` | Get a shell command’s status and exit code. |
+| `ghostdock sandboxes commands kill <command-id> --sandbox-id <string> --session-id <string> [flags]` | Interrupt a running shell command. |
+| `ghostdock sandboxes commands logs <command-id> --sandbox-id <string> --session-id <string> [flags]` | Get a page of a shell command’s stdout and stderr. |
+| `ghostdock sandboxes commands run <sandbox-id> --command <string> [flags]` | Run a shell command in a sandbox. |
+| `ghostdock sandboxes create --source <object> [flags]` | Create a sandbox from a snapshot, OCI image, Dockerfile or Compose files. |
+| `ghostdock sandboxes delete <sandbox-id> [flags]` | Permanently delete a sandbox and its files. |
+| `ghostdock sandboxes env delete <name> --sandbox-id <string> [flags]` | Delete one of a sandbox’s own variables or secrets. |
+| `ghostdock sandboxes env get <sandbox-id> [flags]` | Get a sandbox’s environment: selections, bindings and local entries. |
+| `ghostdock sandboxes env select <sandbox-id> --environment <array> [flags]` | Replace the organization entries a sandbox exports. |
+| `ghostdock sandboxes env set <name> --sandbox-id <string> --value <string> [flags]` | Create or replace one of a sandbox’s own variables or secrets. |
+| `ghostdock sandboxes files list <sandbox-id> [flags]` | List the files in a sandbox directory (default /workspace). |
+| `ghostdock sandboxes files read <path> --sandbox-id <string> [flags]` | Read a file from a sandbox: utf8 text, or base64 for small binaries. |
+| `ghostdock sandboxes files upload <sandbox-id> [path] [flags]` | Upload local files or directories to a sandbox using multipart form data. |
+| `ghostdock sandboxes list [flags]` | List the sandboxes of an organization, including whether each is ephemeral. |
+| `ghostdock sandboxes mcps create <sandbox-id> --name <string> --port <integer> [flags]` | Expose an MCP server running in a sandbox. |
+| `ghostdock sandboxes mcps delete <mcp-id>` | Delete an MCP endpoint of a sandbox. |
+| `ghostdock sandboxes mcps list <sandbox-id> [flags]` | List the MCP endpoints a sandbox exposes (name, port, path, autoWake). |
+| `ghostdock sandboxes mcps update <mcp-id> [flags]` | Change an MCP endpoint’s name, port, path or autoWake setting. |
+| `ghostdock sandboxes resize <sandbox-id> [flags]` | Change a sandbox’s CPU and/or memory. |
+| `ghostdock sandboxes resize-disk <sandbox-id> --disk-gib <number> [flags]` | Grow a sandbox’s disk. |
+| `ghostdock sandboxes set-boot <sandbox-id> --command <string> [flags]` | Register a command that starts now and again after every restart. |
+| `ghostdock sandboxes shells close <session-id> --sandbox-id <string> [flags]` | Close a shell session. |
+| `ghostdock sandboxes shells create <sandbox-id> [flags]` | Open a shell session that keeps cwd and environment between commands. |
+| `ghostdock sandboxes ssh get <sandbox-id> [flags]` | Get temporary SSH access to a sandbox (command and token, 60 minutes). |
+| `ghostdock sandboxes ssh revoke <sandbox-id> [flags]` | Revoke a sandbox’s active SSH access. |
+| `ghostdock sandboxes status <sandbox-id> [flags]` | Get a sandbox’s status and lifecycle deadlines without waking it. |
+| `ghostdock sandboxes stop <sandbox-id> [flags]` | Stop a running sandbox without deleting its files. |
+| `ghostdock sandboxes tools call <name> --sandbox-id <string> --arguments <object> [flags]` | Call a tool on an MCP server inside a sandbox. |
+| `ghostdock sandboxes tools list <sandbox-id> [flags]` | List the tools of the MCP servers a sandbox exposes. |
+| `ghostdock sandboxes update <sandbox-id> [flags]` | Change a sandbox’s display name, idle-stop or auto-delete interval. |
+| `ghostdock sandboxes urls create <sandbox-id> --port <integer> [flags]` | Expose a sandbox port as a URL. |
+| `ghostdock sandboxes urls delete <url-id>` | Delete a sandbox URL. |
+| `ghostdock sandboxes urls list <sandbox-id> [flags]` | List the URLs that expose a sandbox’s ports, with protocol, access and title. |
+| `ghostdock sandboxes urls update <url-id> [flags]` | Change a sandbox URL’s port, protocol, autoWake, public setting or title. |
+| `ghostdock sandboxes wake <sandbox-id> [flags]` | Start a stopped sandbox, or reset the idle-stop countdown of a running one. |
+
+#### sites
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock sites publish [path] [flags]` | Publish a local directory or ZIP to the CDN. |
+| `ghostdock sites unpublish <site-id> [flags]` | Take a published static site offline. |
+
+#### skills
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock skills get <uri>` | Print one SKILL.md (URI from the discovery index, or a skill name). |
+| `ghostdock skills list` | List the Agent Skills discovery index. |
+
+#### snapshots
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock snapshots create <sandbox-id> --name <string> [flags]` | Save a sandbox’s filesystem as a reusable organization snapshot. |
+| `ghostdock snapshots delete <snapshot-id> [flags]` | Permanently delete an organization snapshot (provider artifact and record). |
+| `ghostdock snapshots get <snapshot-id> [flags]` | Get one snapshot with its manifest and required environment, URLs and MCPs. |
+| `ghostdock snapshots list [flags]` | List the snapshots an organization can boot sandboxes from. |
+| `ghostdock snapshots update-manifest <snapshot-id> --manifest <object> [flags]` | Replace a snapshot’s manifest (URLs, environment, MCPs). |
+
+#### tools
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock tools` | List available agent tools. |
+
+#### whoami
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock whoami` | Show the account this CLI is currently authenticated as. |
+<!-- generated:command-index:end -->
+
+## CLI settings
+
+Environment variables read by the CLI process itself. For an organization's environment variables
+and secrets, see [`ghostdock env`](#ghostdock-env).
+
+| Variable                       | Purpose                                                      | Default                          |
+| ------------------------------- | ------------------------------------------------------------- | --------------------------------- |
+| `GHOSTDOCK_BASE_URL`           | API origin the CLI talks to. Override for local dev / self-hosted instances. | Local/dev builds default to `http://localhost:3000`. npm-published builds default to the production API origin baked at publish time. Override with `--base-url` or this env var. |
+| `GHOSTDOCK_ORG`                | Organization (id or slug) for commands run without `--org`. Takes precedence over the default from `organizations use`. | unset |
+| `GHOSTDOCK_CREDENTIALS_PATH`   | Absolute path to the credentials file, overriding the default. `settings.json` (the default organization) sits in the same directory. | `./.ghostdock/credentials.json` (relative to the current working directory) |
+
+Example for local development against a Nuxt dev server:
+
+```bash
+ghostdock --base-url http://localhost:3000 login --wait
+# or
+GHOSTDOCK_BASE_URL=http://localhost:3000 ghostdock login --wait
+```
+
+## Credentials file
+
+Credentials are stored as JSON at `./.ghostdock/credentials.json` (relative to the directory the
+CLI is run from), with file permissions restricted to the owner (`0600`):
+
+```json
+{
+  "accessToken": "ext_at_...",
+  "refreshToken": "ext_rt_...",
+  "accessExpiresAt": "2026-07-30T12:00:00.000Z"
+}
+```
+
+**Add `.ghostdock/` to your project's `.gitignore`.** These are live tokens — never commit them.
+This repository's own `.gitignore` already ignores `.ghostdock/` for local development/testing of
+the CLI itself.
+
+Access tokens are short-lived (1 hour); the CLI refreshes them automatically using the refresh token
+(30-day rolling expiry) whenever a request gets a `401`. If both tokens are invalid or revoked (e.g.
+after `ghostdock logout` from another session), re-run `ghostdock login`.
+
+## Exit codes
+
+- `0` — success (including the default `login` after only printing the URL — approval is still
+  pending, that's expected).
+- `1` — failure: not logged in, session expired and unrefreshable, login denied/expired/timed out,
+  a missing/invalid tool flag, or a tool invocation error (e.g. not a member of the organization).