ghostdock 0.0.19 → 0.1.0

package/dist/cli.md

@@ -1,923 +0,0 @@
-# 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 docker          Docker over the private network: a sandbox's Docker engine from this machine.
-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 machine…
-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>`, stored in
-   `~/.config/ghostdock/settings.json`
-
-With one organization there is nothing to do: `login` makes it the default, and every command,
-in any directory, uses it.
-
-```bash
-ghostdock organizations use acme      # the default (login sets one when it can)
-ghostdock sandboxes list              # stderr: Using organization acme (default from ~/.config/ghostdock/settings.json)
-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, so it belongs to
-the same 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.
-
-Credentials are stored per machine, in `~/.config/ghostdock/credentials.json` (see
-[Credentials file](#credentials-file)), so one login works in every directory.
-
-**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 credentials file. The default organization
-stays.
-
-### `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
-```
-
-#### Containers in a sandbox
-
-On Ghostdock Cloud a sandbox runs one Docker engine; everything in it is an ordinary container.
-`ssh get`, `files`, `commands` and `shells` land in one of them: `--container <name>`, else the
-sandbox's default container, else the one running container. With several running and no default,
-the CLI asks which one at the keyboard and offers to make it the default; without a terminal it
-fails and lists the names. A command runs as `docker exec` does there: as the container's
-`ghostdock.login.user`, else the image's `USER`, else root.
-
-```bash
-ghostdock sandboxes containers list quiet-harbor
-ghostdock sandboxes default-container quiet-harbor --container web     # --clear true removes it
-ghostdock sandboxes commands run quiet-harbor --container db --command 'pg_isready'
-ghostdock sandboxes containers protection quiet-harbor workstation --protected false
-```
-
-A shell session lives in its container: pass the same `--container` to every `shells` and
-`commands` call on it.
-
-#### 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
-ghostdock sandboxes files upload quiet-harbor ./dist --container web --start
-```
-
-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.
-The files land in a container as the other `files` commands do (see
-[Containers in a sandbox](#containers-in-a-sandbox)): `--container <name>`, else the default,
-else the one running, and the CLI asks which one when it cannot tell. A stopped target container
-is started after a "Start it?" at the keyboard, or at once with `--start`.
-
-### `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 organizations' 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.acme.ghostdock.internal/`, as it would on `localhost` inside the sandbox.
-Nothing reaches your machine from a sandbox.
-
-```bash
-ghostdock network connect              # your organization's default provider; sudo once
-ghostdock network connect helsinki     # or name a provider (name or id)
-ghostdock network ls --org acme        # sandboxes, addresses, names, and what is reachable
-curl http://quiet-harbor.acme.ghostdock.internal:8080/
-open https://quiet-harbor--acme.ghostdock.net:8080/   # in a browser: HTTPS, any port
-open https://quiet-harbor.ghostdock.net:8080/         # the short name, for the connect organization
-ghostdock network connect --org beta   # short names now mean beta's sandboxes
-ghostdock network status
-ghostdock network disconnect
-```
-
-- **One provider at a time.** Each sandbox provider is its own gateway, and a device reaches
-  only the sandboxes on the provider it connected through. Without an argument, `connect` takes
-  the organization (`--org`, `GHOSTDOCK_ORG`, the default from `organizations use`) and its
-  default sandbox provider, else the platform default. Connecting through another provider
-  replaces the connection: same interface and address, new gateway. `network status` says which
-  provider you are connected through; `network ls` marks sandboxes elsewhere as
-  `not reachable: on <provider>` with the `connect` command that reaches them. A provider
-  without a private network (Incus, for now) is refused by the server; one your organization
-  may not use answers 403.
-- **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.
-- **Tunnel MTU 1280**, so the tunnel works on networks with a smaller path than 1500 bytes
-  (DS-Lite, VPNs, mobile). A config written before 2026-10-20 has 1420: `network status` and
-  `network ls` then say *This machine's tunnel has MTU 1420, the network now uses 1280*. Run
-  `ghostdock network connect` again; until then TCP works, other large packets can be lost.
-- **One key per machine**, kept in `~/.config/ghostdock/network/`.
-  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`, for every organization you are a member
-  of. A name always says its organization, so a browser origin never changes hands between
-  organizations. Only AAAA records exist: the network is IPv6, and the sandbox sees IPv4.
-- **In a browser**, use the HTTPS name `https://<sandbox>--<org>.ghostdock.net:<port>`
-  (`network ls` shows it): any port, a real certificate, so the page is a secure context
-  (clipboard, `Secure` cookies, service workers). The host's `gdo-ingress` terminates TLS and
-  forwards to the sandbox's port; it serves only devices of the sandbox's organization, and
-  refuses background requests (fetch, forms, iframes, websockets) from pages outside that
-  organization; pages on another HTTPS name of the same organization, any port, may call it. The
-  sandbox sees the request from `198.18.0.0`, and your device's address in
-  `X-Forwarded-For`. The desktop image's Desktop opens only this way, never on the raw
-  address.
-- **Short names** in a browser: `https://<sandbox>.ghostdock.net:<port>` means the sandbox of
-  this machine's organization: the one `network connect` resolved (`--org`, `GHOSTDOCK_ORG`,
-  the default from `organizations use`). `connect` says which; `network status` too, and
-  `network ls` shows a sandbox's short name next to its full one when it is that
-  organization's. With one organization you need nothing else. To use another organization's
-  short names, connect again with `--org <other>`: there is no other way to change it, so a
-  short name never changes meaning behind your back (`cd` into another project does not
-  change it). Full names (`<sandbox>--<org>`) keep working for every organization and never
-  change meaning: use them in scripts, CI, `.env` files and links you share.
-  - **When the organization changes,** each short-name site clears its browser data once
-    (local storage, cache, cookies) before the other organization's sandbox sees a request, so
-    it never reads the first one's data. Cookies are cleared for the whole site, not only the
-    short name: every site under the net domain's registrable domain (`ghostdock.net`: every
-    sandbox app there, full names included; a net domain under the app's domain, as on staging:
-    the Ghostdock app too). `connect` names the site when the organization changes. A tab opened on a short name before the
-    change keeps the old page until you reload it: reload or close those tabs (`connect` says
-    so). The page *Switching organization* is that clearing and reloads by itself; *Clear this
-    site's data* means your browser could not clear it (Safari before 17): clear the site's
-    data in its settings, or use the full name.
-  - Tools may use short names too (`curl https://quiet-harbor.ghostdock.net:8080/`), but a
-    short name in a script means whatever this machine is connected with: prefer the full
-    name.
-- **Browsers use the HTTPS name; tools keep the raw address.** A browser that opens
-  `http://quiet-harbor.acme.ghostdock.internal:3000/app` (or the raw IPv6 address) gets a
-  `308` to `https://quiet-harbor--acme.ghostdock.net:3000/app`. Any other browser request on
-  the raw address (`fetch`, images, scripts, forms, websockets) gets `403` with
-  `X-Ghostdock-Blocked: browser-https-only` and the HTTPS address in the body. This keeps
-  websites you visit while connected from using your connection against your sandboxes,
-  including through DNS rebinding.
-  - **What counts as a browser:** a `User-Agent` that starts with `Mozilla/`, which every
-    browser sends on its own requests. Browsers send no `Sec-Fetch-*` headers over plain
-    `http://` to an address like this, so those cannot be the signal. (Firefox lets a page
-    set its own `User-Agent` on a `fetch`; the `Host` check below stops that one.) Tools that send a
-    browser's `User-Agent` (Playwright, Puppeteer, their request APIs) count as browsers too:
-    point them at the HTTPS name. A frontend outside the sandbox (a dev server on your laptop)
-    calls the sandbox's API by its HTTPS name as well.
-  - **Tools** (`curl`, SDKs, test runners, Prometheus) pass untouched, and every other
-    protocol does too, as long as they address the sandbox by its IP address, its
-    `.internal` name (or a container's, `web.quiet-harbor.acme.ghostdock.internal`), or
-    `localhost`: any other `Host` gets `421` (`X-Ghostdock-Blocked: host-not-allowed`). That
-    check is what stops DNS rebinding for a page that sets its own `User-Agent`. A name of
-    your own in `/etc/hosts` gets 421 too.
-  - **One difference for tools:** a port where nothing listens accepts the connection and
-    then resets it, so port checks such as `nc -z` report it open; check with a real request
-    instead.
-  - **In the sandbox,** firewall rules for these clients belong in the input path
-    (`iptables -A INPUT`, an nft `hook input` chain): `FORWARD` and `DOCKER-USER` rules no
-    longer see them, because the guard connects to a published container port from inside
-    the VM.
-- **The network pause** ([ADR 0033](../../docs/adr/0033-gdo-net-dead-mans-switch.md)): a
-  device that sent no traffic to a sandbox for its idle timeout (default 4 h), or whose session
-  since the last connect reached its maximum (default 12 h), is paused at the gateway. Your
-  organizations set both (Settings → Security). If you are in several, the strictest value
-  applies. `connect` ends with this device's own numbers and names the organization that set a
-  stricter one.
-  - **While paused**, names still resolve, but every port of a sandbox answers `Connection
-    refused`, and UDP and ping get *administratively prohibited*. Browsers get a pause page
-    with a *Reconnect* button, and Docker gets `Ghostdock: network access for this device is
-    paused (idle 4 h)`. Every `ghostdock` command prints `! Network access for this device is
-    paused (…). Run: ghostdock network connect` once.
-  - **To resume**, run `ghostdock network connect`, or click *Reconnect* in the web app (User
-    settings → Network devices). With the tunnel up and nothing changed, `connect` only
-    re-arms: no sudo, *Re-armed: network access for this device runs until 22:14 (pauses after
-    4 h idle).* *Pause now* in the web app pauses a device at once.
-  - DNS, WireGuard keepalives and ping do not count as traffic. A long stream does (a `docker
-    logs -f`, an open desktop tab).
-- `ghostdock network devices` lists your devices with their state (*Active, pauses in 3 h 12
-  min*, *Paused: idle 4 h*, *Paused: 12 h session limit*, *Paused by you*, *Not connected
-  (…)*). `ghostdock network devices remove <id>` removes one.
-- **`ghostdock network disconnect`** also removes the split-DNS files a reboot or a crashed
-  `wg-quick` left on macOS (`/etc/resolver/<zone>`), even when the tunnel is already down.
-  Without that, names of the private network hang while you are disconnected. `network status`
-  says when such a file is still there.
-
-### `ghostdock docker context`
-
-Point your own `docker` and `docker compose` at a sandbox's Docker engine, over the private
-network with mutual TLS ([ADR 0032](../../docs/adr/0032-docker-api-over-gdo-net.md)). Connect
-first: the context uses this machine's device.
-
-```bash
-ghostdock network connect
-ghostdock docker context quiet-harbor --org acme
-#   ✓ Docker context ghostdock-acme-quiet-harbor (in use)
-#       tcp://quiet-harbor.acme.ghostdock.internal:2376
-#       Certificate for this device, valid until 2026-11-20.
-#       → docker ps
-docker ps
-docker compose up -d
-ghostdock docker context north-pier --no-use   # create only: docker --context ghostdock-acme-north-pier ps
-```
-
-- **One Docker context per sandbox**, `ghostdock-<org>-<sandbox>`, for
-  `tcp://<sandbox>.<org>.ghostdock.internal:2376`. Running the command again updates it;
-  without `--no-use` it also becomes Docker's current context (`docker context use`). A
-  `DOCKER_HOST` or `DOCKER_CONTEXT` in your shell wins over that: the command says so.
-- **One client certificate per organization and machine**, in
-  `~/.config/ghostdock/docker/<organizationId>/`: `key.pem` (ECDSA P-256, made on this machine,
-  0600; only a certificate request is sent), `cert.pem` and `ca.pem`. The certificate names your
-  user, this machine's device and the organization, and lives 30 days. A new one replaces the
-  earlier one of this device for that organization: the old one stops working at once.
-- **Renewal:** `ghostdock network connect` and `ghostdock docker context` renew every
-  certificate of this machine with less than 10 days left, and update the contexts they wrote
-  (`~/.config/ghostdock/docker/contexts.json`). An expired certificate fails Docker's TLS
-  handshake with Docker's own error: run `ghostdock docker context <sandbox>` again.
-- **`no such host`** on a `ghostdock.internal` address means this machine is not connected:
-  run `ghostdock network connect`. The context's description in `docker context ls` says so
-  too.
-- **Renamed organization:** the context's host keeps the old name, which stops resolving. Run
-  `ghostdock docker context <sandbox>` again to update the host.
-- **Only from this device:** the sandbox checks every request with the app (membership, device,
-  the network pause). A copied key and certificate do not work from another machine; a refusal
-  comes back as Docker's `Error response from daemon: Ghostdock: …` with what to run.
-- **Warnings:** a sandbox on another provider than this machine's connection (with the
-  `network connect` command that reaches it), and a sandbox whose base image is too old for
-  Docker over the network (restart it to update). A sandbox that cannot have a Docker engine
-  over the network (its provider has no private network, it has no address there yet, or a
-  name that is not a DNS label) gets no context, and the command says why.
-- **A stopped sandbox** gets its context too: the first connection to it starts it (wake on
-  SYN), and its Docker engine answers once it runs. A start that takes longer than Docker's
-  32 s dial timeout fails that one command with Docker's `i/o timeout`; the next one works.
-- **Needs Docker's CLI** (`docker` on `PATH`: Docker Desktop, OrbStack, or the CLI alone). The
-  Docker engine itself runs in the sandbox.
-
-## 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. |
-
-#### docker
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock docker context <sandbox> [flags]` | Point Docker at a sandbox's Docker engine over the private network: plain… |
-
-#### 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> [flags]` | Add a Compose project 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, reference, override 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 machine… |
-
-#### logout
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock logout` | Revoke the device session and remove stored credentials. |
-
-#### network
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock network connect [provider] [flags]` | Put this machine into the private network through one provider: WireGuard and… |
-| `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, and remove split DNS an earlier… |
-| `ghostdock network ls [flags]` | Sandboxes of an organization with their private addresses and names, and which… |
-| `ghostdock network status` | Whether this machine is connected, through which provider, and as which device. |
-
-#### 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 without --org (in every… |
-
-#### 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 containers list <sandbox-id> [flags]` | List the containers of a sandbox, running or not. |
-| `ghostdock sandboxes containers lock <sandbox-id> <container> [flags]` | Lock a container against removal. |
-| `ghostdock sandboxes containers logs <sandbox-id> <container> [flags]` | Read a container’s output, as docker logs does. |
-| `ghostdock sandboxes containers restart <sandbox-id> <container> [flags]` | Restart a container, as docker restart does (stopping as docker stop does). |
-| `ghostdock sandboxes containers start <sandbox-id> <container> [flags]` | Start a stopped container, as docker start does. |
-| `ghostdock sandboxes containers stop <sandbox-id> <container> [flags]` | Stop a container, as docker stop does. |
-| `ghostdock sandboxes containers unlock <sandbox-id> <container> [flags]` | Unlock a container so Docker can remove or recreate it. |
-| `ghostdock sandboxes create --source <object> [flags]` | Create a sandbox from a snapshot, OCI image, Dockerfile or Compose files. |
-| `ghostdock sandboxes default-container <sandbox-id> [flags]` | Show, set or clear the sandbox’s default container. |
-| `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. |
-| `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's container, into its start… |
-| `ghostdock sandboxes list [flags]` | List the sandboxes of an organization, with their lifecycle and deadlines. |
-| `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 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 storage delete <sandbox-id> --kind <string> --name <string> [flags]` | Delete a named volume or a top-level sandbox folder, with everything in it. |
-| `ghostdock sandboxes storage list <sandbox-id> [flags]` | List a sandbox’s volumes and sandbox folders. |
-| `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 interval or lifecycle. |
-| `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 |
-| `XDG_CONFIG_HOME`              | Base directory for the CLI's per-machine state (`ghostdock/credentials.json`, `ghostdock/settings.json`, `ghostdock/network/`, `ghostdock/docker/`). | `~/.config` (native Windows: `%APPDATA%`) |
-| `GHOSTDOCK_CREDENTIALS_PATH`   | Absolute path to the credentials file, overriding the default. `settings.json` (the default organization) sits in the same directory, so each credentials file keeps its own default — handy for a second account. | `~/.config/ghostdock/credentials.json` |
-
-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 per machine as JSON in `~/.config/ghostdock/credentials.json`
-(`$XDG_CONFIG_HOME/ghostdock/` when that is set, `%APPDATA%\ghostdock\` on native Windows; WSL
-counts as Linux), with file permissions restricted to the owner (`0600`). `GHOSTDOCK_CREDENTIALS_PATH`
-points the CLI at another file, e.g. for a second account. The file looks like this:
-
-```json
-{
-  "accessToken": "ext_at_...",
-  "refreshToken": "ext_rt_...",
-  "accessExpiresAt": "2026-07-30T12:00:00.000Z"
-}
-```
-
-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).