ghostdock 0.0.20 → 0.1.0

package/dist/cli.md

@@ -1,934 +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 vm list
-  ⚓ Marketing site  quiet-harbor  running
-  ◌ teal-jetty  stopped
-$ ghostdock site 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 VM
-(`vm create`, `vm wake`) prints how long each step took, measured on the server, each
-step with its own time:
-
-```
-$ ghostdock vm wake quiet-harbor
-  ⚓ quiet-harbor  running
-  ⚓ VM 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. `vm status` prints the same lines for the last start. With `--json` they are
-the `boot` field: `{ trigger, vm: { 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 vm list --json | jq -r '.vms[].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 app            Published apps of an organization.
-ghostdock docker         Docker over the private network: a VM's Docker engine from this machine.
-ghostdock env            Manage organization environment variables and secrets.
-ghostdock image          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 VMs by address and name from this machine.
-ghostdock organization   Organizations you belong to.
-ghostdock project        Deployable projects, their deployments and environment.
-ghostdock provider       Providers of an organization.
-ghostdock registry       Log in to the organization container registry.
-ghostdock site           Static sites on the CDN.
-ghostdock skill          List and read Agent Skills (same catalog as MCP skill://index.json).
-ghostdock snapshot       VM snapshots.
-ghostdock template       
-ghostdock tools          List available agent tools.
-ghostdock vm             Create, run and manage VMs.
-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 vm --help` or `ghostdock vm url 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 organization 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 organization use acme      # the default (login sets one when it can)
-ghostdock vm list              # stderr: Using organization acme (default from ~/.config/ghostdock/settings.json)
-ghostdock vm list --org beta   # --org always wins
-ghostdock organization current       # which organization, and where it comes from
-ghostdock organization 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 VM 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 organization 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 skill`
-
-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 `skill_list` and `skill_get` are fallbacks for clients that
-cannot use `resources/list` and `resources/read` — skip them if those work.
-
-```bash
-ghostdock skill list                          # name, description, and skill:// URI per skill
-ghostdock skill list --json                   # official discovery index ($schema + skills[])
-ghostdock skill get skill://github/SKILL.md   # print SKILL.md
-ghostdock skill get github                    # same, by name
-ghostdock skill 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
-(`autoWake` -> `--auto-wake`). The one thing a command acts on is positional instead:
-`ghostdock vm stop <vm>`, `ghostdock vm url 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 vm url create` calls the `vm_url_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 organization list
-#   • Acme  org_123
-ghostdock organization 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 skill get vm       # sources, manifests, lifecycle, providers, URLs and TCP
-ghostdock skill get vm-boot   # processes that must come back after idle-stop
-ghostdock skill get environment    # organization entries, bindings, local entries, secrets
-ghostdock skill get publishing     # sites publish vs projects publish, outcomes, redeploys
-ghostdock skill get incus-setup    # connecting your own Incus host
-```
-
-### VMs
-
-Read `ghostdock skill get vm` before your first VM: what it can boot from, manifests,
-idle-stop and auto-delete, providers, URLs.
-
-Every VM has a name like `quiet-harbor`, unique within its organization, and every command
-that takes a VM accepts it with the organization (`--org`, `GHOSTDOCK_ORG` or the default).
-The long `vmId` in `--json` output works too, in the same organization. A name never changes
-while the VM exists, so scripts can keep it; once a VM 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 VM,
-then expose a URL:
-
-```bash
-ghostdock vm create --org org_123 --display-name "Marketing site"
-ghostdock vm url create quiet-harbor --port 8080 --auto-wake true --public true
-```
-
-#### Containers in a VM
-
-On Ghostdock Cloud a VM runs one Docker engine; everything in it is an ordinary container.
-`vm ssh get`, `vm file`, `vm command` and `vm shell` land in one of them: `--container <name>`, else the
-VM'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 vm container list quiet-harbor
-ghostdock vm default-container quiet-harbor --container web     # --clear true removes it
-ghostdock vm command run quiet-harbor --container db --command 'pg_isready'
-ghostdock vm container unlock quiet-harbor workstation
-```
-
-A shell session lives in its container: pass the same `--container` to every `shells` and
-`commands` call on it.
-
-#### Environment in a VM
-
-A VM 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` (VM-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 vm 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 vm env get quiet-harbor
-ghostdock vm env select quiet-harbor --environment '["VITE_API_URL"]' \
-  --bindings '[{"name":"DATABASE_URL","organization":"PROD_DATABASE_URL"}]'
-ghostdock vm env select quiet-harbor --environment '[]'   # clears plain + remaps (omit bindings)
-ghostdock vm env set API_KEY --vm quiet-harbor --value sk_live --kind secret
-ghostdock vm env delete API_KEY --vm quiet-harbor
-```
-
-Values arrive as real environment variables, so read them with `process.env` / `$VAR` inside the
-VM. **Do not pass secrets in `vm command run` strings** — the command text is retained and
-readable through `vm command logs`. `vm env get` reports every organization entry
-(selected + overriddenByLocal) and the VM's own local entries; `vm 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 `vm env select` /
-`vm env set` / `vm env delete` to restart a running VM
-instead).
-
-### Images
-
-Organization image catalog: OCI bookmarks (`image add`), stored Dockerfiles
-(`image add-dockerfile`), and refs currently in use on VMs. `image list` and `image 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). `vm create` with `--source '{"type":"image","id":"..."}'` boots a catalog
-row by id and applies its manifest (URLs + env) like an organization snapshot.
-
-```bash
-ghostdock image list --org org_123
-ghostdock image get img_abc --org org_123
-ghostdock image add --org org_123 --ref ghcr.io/acme/app:latest --label "Acme app"
-ghostdock image add-dockerfile --org org_123 --name my-stack --dockerfile "$(cat Dockerfile)"
-ghostdock vm 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 vm build`](#ghostdock-vm-build), not this command. Any OCI ref may still
-be passed as `{ type: "image", ref }` even when it does not appear in `image list`. Catalog compose
-rows still boot via `{ type: "image", id }`.
-
-### `ghostdock site publish`
-
-Publish a local directory or ZIP to the CDN (durable public URL, no VM):
-
-```bash
-ghostdock site publish --org org_123 ./dist
-ghostdock site publish --org org_123 --zip ./site.zip
-```
-
-MCP `site_publish` is for small inline payloads. Use this command for a real directory or large ZIP.
-
-### `ghostdock project 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 `vm create`) after configuring.
-On `build_failed`, `start_failed`, or `verify_failed`, inspect the kept VM (unless verification tore it down), then re-invoke with `--spec` (JSON `DeploymentSpec`). The spec is executed on a fresh VM 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 project publish --org org_123 ./app
-ghostdock project publish --org org_123 --auto-stop-interval-minutes -1 --zip ./app.zip
-ghostdock project publish --org org_123 --project-id proj_123 ./app
-ghostdock project publish --org org_123 ./app \
-  --environment '{"organization":["DATABASE_URL"],"local":[{"name":"API_KEY","value":"sk_live","kind":"secret"}]}'
-ghostdock project publish --org org_123 ./app --spec '{"version":1,"run":{"kind":"static","outputDir":"."},"env":[]}'
-ghostdock project publish --org org_123 --require-verify ./app
-ghostdock project publish --org org_123 --provider prov_123 ./app
-```
-
-MCP `project_publish` is for small inline payloads. Use this command for a real directory or large ZIP.
-
-### `ghostdock vm build`
-
-Create a VM from a local Dockerfile or Compose directory. The CLI zips the directory (or sends
-`--zip`) and the server builds it. MCP `vm_create` stays inline text only.
-
-```bash
-ghostdock vm build --org org_123 --kind dockerfile ./app
-ghostdock vm build --org org_123 --kind compose --zip ./stack.zip
-ghostdock vm build --org org_123 --kind dockerfile \
-  --provider 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 vm file upload`
-
-`vm file 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 vm file upload quiet-harbor ./dist
-ghostdock vm file upload quiet-harbor ./index.html ./assets
-ghostdock vm file upload quiet-harbor --zip ./site.zip
-ghostdock vm file 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 `vm file upload` call needs
-at least one path or `--zip`. Uploading to a stopped VM resumes it automatically.
-The files land in a container as the other `vm file` commands do (see
-[Containers in a VM](#containers-in-a-vm)): `--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 VMs and projects.
-A VM inherits nothing automatically — select the entries it needs on that VM.
-
-```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 VM 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' VMs from this machine by private address and name, over
-WireGuard ([ADR 0027](../../docs/adr/0027-private-sandbox-network.md)). Everything on a
-VM'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 VM.
-Nothing reaches your machine from a VM.
-
-```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        # VMs, 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 VMs
-ghostdock network status
-ghostdock network disconnect
-```
-
-- **One provider at a time.** Each provider is its own gateway, and a device reaches
-  only the VMs on the provider it connected through. Without an argument, `connect` takes
-  the organization (`--org`, `GHOSTDOCK_ORG`, the default from `organization use`) and its
-  default 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 VMs 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 VMs.
-- **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**: `<vm>.<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 VM sees IPv4.
-- **In a browser**, use the HTTPS name `https://<vm>--<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 VM's port; it serves only devices of the VM'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
-  VM 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://<vm>.ghostdock.net:<port>` means the VM of
-  this machine's organization: the one `network connect` resolved (`--org`, `GHOSTDOCK_ORG`,
-  the default from `organization use`). `connect` says which; `network status` too, and
-  `network ls` shows a VM'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 (`<vm>--<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 VM 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
-    VM 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 VMs,
-  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 VM (a dev server on your laptop)
-    calls the VM'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 VM 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 VM,** 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 VM 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 VM 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 VM'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 VM**, `ghostdock-<org>-<vm>`, for
-  `tcp://<vm>.<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 <vm>` 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 <vm>` again to update the host.
-- **Only from this device:** the VM 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 VM on another provider than this machine's connection (with the
-  `network connect` command that reaches it), and a VM whose base image is too old for
-  Docker over the network (restart it to update). A VM 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 VM** 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 VM.
-
-## 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) -->
-#### app
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock app list [flags]` | List the live published apps (sites) of an organization, with their URLs. |
-
-#### docker
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock docker context <vm> [flags]` | Point Docker at a VM's Docker engine over the private network: plain `docker`… |
-
-#### 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. |
-
-#### image
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock image add --ref <string> [flags]` | Bookmark an OCI image ref in the organization’s image catalog. |
-| `ghostdock image add-compose --name <string> [flags]` | Add a Compose project to the organization’s image catalog. |
-| `ghostdock image add-dockerfile --name <string> --dockerfile <string> [flags]` | Add a Dockerfile to the organization’s image catalog. |
-| `ghostdock image get <image-id> [flags]` | Get one catalog image with its spec, manifest and requirements. |
-| `ghostdock image list [flags]` | List the images an organization can boot VMs from. |
-| `ghostdock image remove <image-id> [flags]` | Remove an image from the organization’s catalog. |
-| `ghostdock image update-compose <image-id> [flags]` | Replace a catalog Compose image’s files, reference, override and/or name. |
-| `ghostdock image 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]` | VMs of an organization with their private addresses and names, and which are… |
-| `ghostdock network status` | Whether this machine is connected, through which provider, and as which device. |
-
-#### organization
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock organization current [flags]` | Show which organization commands use, and where it comes from. |
-| `ghostdock organization list` | List the organizations you belong to, with their ids and slugs. |
-| `ghostdock organization use [org] [flags]` | Set the default organization for commands run without --org (in every… |
-
-#### project
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock project create --display-name <string> [flags]` | Create an empty project. |
-| `ghostdock project deployment get <deployment-id> --project-id <string> [flags]` | Get one deploy attempt, with links to its stored files. |
-| `ghostdock project deployment list <project-id> [flags]` | List a project’s deploy attempts, newest first. |
-| `ghostdock project env delete <name> --project-id <string> [flags]` | Delete one of a project’s own variables or secrets. |
-| `ghostdock project env get <project-id> [flags]` | Get a project’s stored environment. |
-| `ghostdock project env select <project-id> --environment <array> [flags]` | Replace the organization entries a project exports. |
-| `ghostdock project env set <name> --project-id <string> --value <string> --kind <string> [flags]` | Create or replace one of a project’s own variables or secrets. |
-| `ghostdock project get <project-id> [flags]` | Get a project with its latest attempt and live deployment. |
-| `ghostdock project list [flags]` | List an organization’s projects. |
-| `ghostdock project publish [path] [flags]` | Inspect local source with the deploy agent and publish to the CDN or a VM. |
-| `ghostdock project redeploy <project-id> [flags]` | Deploy a project’s stored source again, with its current environment. |
-| `ghostdock project update <project-id> --display-name <string> [flags]` | Rename a project. |
-
-#### provider
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock provider disconnect <provider> [flags]` | Disconnect one of the organization’s own providers. |
-| `ghostdock provider list [flags]` | List the providers an organization can create VMs on. |
-| `ghostdock provider rename <provider> --name <string> [flags]` | Rename one of the organization’s own providers. |
-| `ghostdock provider set-default <provider> [flags]` | Set the provider used when a create omits provider. |
-| `ghostdock provider start-incus [flags]` | Start connecting an Incus host as a provider. |
-| `ghostdock provider verify-incus <provider> [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. |
-
-#### site
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock site publish [path] [flags]` | Publish a local directory or ZIP to the CDN. |
-| `ghostdock site unpublish <site-id> [flags]` | Take a published static site offline. |
-
-#### skill
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock skill get <uri>` | Print one SKILL.md (URI from the discovery index, or a skill name). |
-| `ghostdock skill list` | List the Agent Skills discovery index. |
-
-#### snapshot
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock snapshot create <vm> --name <string> [flags]` | Save a VM’s filesystem as a reusable organization snapshot. |
-| `ghostdock snapshot delete <snapshot-id> [flags]` | Permanently delete an organization snapshot (provider artifact and record). |
-| `ghostdock snapshot get <snapshot-id> [flags]` | Get one snapshot with its manifest and required environment, URLs and MCPs. |
-| `ghostdock snapshot list [flags]` | List the snapshots an organization can boot VMs from. |
-| `ghostdock snapshot update-manifest <snapshot-id> --manifest <object> [flags]` | Replace a snapshot’s manifest (URLs, environment, MCPs). |
-
-#### template
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock template create --name <string> --title <string> --spec <object> [flags]` | Save a VM create request as a template of the organization. |
-| `ghostdock template delete <template> [flags]` | Delete a template of the organization by its name. |
-| `ghostdock template list [flags]` | List the templates to create a VM from (headless, desktop, nginx, …). |
-| `ghostdock template update <template> [flags]` | Change a template of the organization by its name. |
-
-#### tools
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock tools` | List available agent tools. |
-
-#### vm
-
-| Command | What it does |
-| --- | --- |
-| `ghostdock vm build [path] --kind <value> [flags]` | Create a VM from a local Dockerfile or Compose directory. |
-| `ghostdock vm command get <command-id> --vm <string> --session-id <string> [flags]` | Get a shell command’s status and exit code. |
-| `ghostdock vm command kill <command-id> --vm <string> --session-id <string> [flags]` | Interrupt a running shell command. |
-| `ghostdock vm command logs <command-id> --vm <string> --session-id <string> [flags]` | Get a page of a shell command’s stdout and stderr. |
-| `ghostdock vm command run <vm> --command <string> [flags]` | Run a shell command in a VM. |
-| `ghostdock vm container list <vm> [flags]` | List the containers of a VM, running or not. |
-| `ghostdock vm container lock <vm> <container> [flags]` | Lock a container against removal. |
-| `ghostdock vm container logs <vm> <container> [flags]` | Read a container’s output, as docker logs does. |
-| `ghostdock vm container restart <vm> <container> [flags]` | Restart a container, as docker restart does (stopping as docker stop does). |
-| `ghostdock vm container start <vm> <container> [flags]` | Start a stopped container, as docker start does. |
-| `ghostdock vm container stop <vm> <container> [flags]` | Stop a container, as docker stop does. |
-| `ghostdock vm container unlock <vm> <container> [flags]` | Unlock a container so Docker can remove or recreate it. |
-| `ghostdock vm create --source <object> [flags]` | Create a VM from a snapshot, OCI image, Dockerfile or Compose files. |
-| `ghostdock vm default-container <vm> [flags]` | Show, set or clear the VM’s default container. |
-| `ghostdock vm delete <vm> [flags]` | Permanently delete a VM and its files. |
-| `ghostdock vm env delete <name> --vm <string> [flags]` | Delete one of a VM’s own variables or secrets. |
-| `ghostdock vm env get <vm> [flags]` | Get a VM’s environment: selections, bindings and local entries. |
-| `ghostdock vm env select <vm> --environment <array> [flags]` | Replace the organization entries a VM exports. |
-| `ghostdock vm env set <name> --vm <string> --value <string> [flags]` | Create or replace one of a VM’s own variables or secrets. |
-| `ghostdock vm file list <vm> [flags]` | List the files in a VM directory. |
-| `ghostdock vm file read <path> --vm <string> [flags]` | Read a file from a VM: utf8 text, or base64 for small binaries. |
-| `ghostdock vm file upload <vm> [path] [flags]` | Upload local files or directories to a VM's container, into its start folder… |
-| `ghostdock vm list [flags]` | List the VMs of an organization, with their lifecycle and deadlines. |
-| `ghostdock vm mcp create <vm> --name <string> --port <integer> [flags]` | Expose an MCP server running in a VM. |
-| `ghostdock vm mcp delete <mcp-id>` | Delete an MCP endpoint of a VM. |
-| `ghostdock vm mcp list <vm> [flags]` | List the MCP endpoints a VM exposes (name, port, path, autoWake). |
-| `ghostdock vm mcp update <mcp-id> [flags]` | Change an MCP endpoint’s name, port, path or autoWake setting. |
-| `ghostdock vm resize <vm> [flags]` | Change a VM’s CPU and/or memory. |
-| `ghostdock vm resize-disk <vm> --disk-gib <number> [flags]` | Grow a VM’s disk. |
-| `ghostdock vm shell close <session-id> --vm <string> [flags]` | Close a shell session. |
-| `ghostdock vm shell create <vm> [flags]` | Open a shell session that keeps cwd and environment between commands. |
-| `ghostdock vm ssh get <vm> [flags]` | Get temporary SSH access to a VM (command and token, 60 minutes). |
-| `ghostdock vm ssh revoke <vm> [flags]` | Revoke a VM’s active SSH access. |
-| `ghostdock vm status <vm> [flags]` | Get a VM’s status and lifecycle deadlines without waking it. |
-| `ghostdock vm stop <vm> [flags]` | Stop a running VM without deleting its files. |
-| `ghostdock vm storage delete <vm> --kind <string> --name <string> [flags]` | Delete a named volume or a top-level VM folder, with everything in it. |
-| `ghostdock vm storage list <vm> [flags]` | List a VM’s volumes and VM folders. |
-| `ghostdock vm tool call <name> --vm <string> --arguments <object> [flags]` | Call a tool on an MCP server inside a VM. |
-| `ghostdock vm tool list <vm> [flags]` | List the tools of the MCP servers a VM exposes. |
-| `ghostdock vm up <template> [flags]` | Create a VM from a template by its name: `ghostdock vm up nginx`. |
-| `ghostdock vm update <vm> [flags]` | Change a VM’s display name, idle-stop interval or lifecycle. |
-| `ghostdock vm url create <vm> --port <integer> [flags]` | Expose a VM port as a URL. |
-| `ghostdock vm url delete <url-id>` | Delete a VM URL. |
-| `ghostdock vm url list <vm> [flags]` | List the URLs that expose a VM’s ports, with protocol, access and title. |
-| `ghostdock vm url update <url-id> [flags]` | Change a VM URL’s port, protocol, autoWake, public setting or title. |
-| `ghostdock vm wake <vm> [flags]` | Start a stopped VM, or reset the idle-stop countdown of a running one. |
-
-#### 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 `organization 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).