ghostdock 0.0.7 → 0.0.9

package/package.json

@@ -1,15 +1,14 @@
 {
   "name": "ghostdock",
   "description": "Ghostdock CLI — device login and agent tool invocation from the command line",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "type": "module",
   "bin": {
     "ghostdock": "dist/index.js",
     "gdock": "dist/index.js"
   },
   "files": [
-    "dist",
-    "CLI.md"
+    "dist"
   ],
   "repository": {
     "type": "git",
@@ -20,8 +19,9 @@
   },
   "scripts": {
     "sync-catalog": "bun run scripts/sync-catalog.ts",
+    "sync-reference": "bun run scripts/sync-reference.ts",
     "needs-publish": "bun run scripts/needs-publish.ts",
-    "prebuild": "bun run sync-catalog",
+    "prebuild": "bun run sync-catalog && bun run sync-reference",
     "build": "bun run scripts/build.ts",
     "dev": "bun run src/index.ts",
     "pretest": "bun run sync-catalog",

package/CLI.md

@@ -1,468 +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
-```
-
-`gdock` is a short name for the same CLI: `npx gdock …`, or `gdock …` after a
-global install. Help and hints use whichever name you typed.
-
-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
-```
-
-## Global flags
-
-```
-ghostdock --version
-ghostdock --base-url <url> <command>
-```
-
-- `--version` / `-v` — print CLI version and exit
-- `--base-url <url>` — API origin for this invocation (wins over `GHOSTDOCK_BASE_URL`)
-
-## Commands
-
-```
-ghostdock login    Sign in and store a device access token for this CLI
-ghostdock logout   Revoke the device session and remove stored credentials
-ghostdock whoami   Show the account this CLI is currently authenticated as
-ghostdock tools    List available agent tools
-ghostdock skills   List and read Agent Skills (same catalog as MCP)
-ghostdock env      Manage organization environment variables and secrets
-ghostdock sandbox_upload  Upload local files or directories to a sandbox
-ghostdock sandbox_create  Create a sandbox from a Dockerfile or Compose directory (or ZIP)
-ghostdock publish_static  Publish a local directory or ZIP to the CDN
-ghostdock publish_auto    Inspect local source and publish (CDN or sandbox)
-```
-
-Every tool in the catalog (e.g. `list_organizations`, `list_published_apps`) is also registered as its
-own top-level command — see **Invoking a tool** below.
-
-Run `ghostdock <command> --help` for the full flag list of any command.
-
-### `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.
-
-### `ghostdock logout`
-
-```bash
-ghostdock logout
-```
-
-Revokes the device session on the server (best-effort — still clears local credentials even if the
-server call fails, e.g. when offline) and deletes the local credentials file.
-
-### `ghostdock whoami`
-
-```bash
-ghostdock whoami
-```
-
-Prints the identity behind the stored access token as 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. `list_skills` and `read_skill` are MCP fallbacks for clients that
-cannot use `resources/list` and `resources/read` — skip them if those work.
-
-```bash
-ghostdock skills          # name, description, and skill:// URI, one skill per block
-ghostdock skills --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 its own top-level command, named after the tool, with one `--flag` per
-schema property (`organizationId` -> `--organization-id`). Run `ghostdock <tool-name> --help` to
-see a tool's flags and which are required. Output is the tool's JSON result on stdout; nothing is
-printed on stderr on success.
-
-```bash
-ghostdock list_organizations
-# {"organizations": [{"id": "org_123", "name": "Acme", "slug": "acme"}]}
-
-ghostdock list_published_apps --organization-id org_123
-# {"apps": [{"id": "app_1", "url": "https://acme.example.app", "title": "Acme App", "publishedAt": "..."}]}
-```
-
-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.
-
-### Sandbox tools
-
-Use sandbox tools to publish and manage public static sites. Each sandbox serves its preview on port
-`8080`; the platform automatically stops idle sandboxes and deletes stopped sandboxes unless you
-override the intervals with `--auto-stop-interval-minutes` and
-`--auto-delete-interval-minutes`. `--auto-restart` defaults to `false`, so wake-on-visit is off for
-new sandboxes unless you set it.
-
-| Tool | Purpose |
-| --- | --- |
-| `create_sandbox` | Create a sandbox (idle-stop + 14-day auto-delete by default). Dockerfile and Compose restart automatically after idle-stop. Inline Dockerfile text and inline Compose files only — a directory or ZIP (COPY/ADD, Compose build files) is `sandbox_create`. For bun-dev, pass an OCI `--source type=image` then `set_sandbox_boot`. |
-| `list_sandboxes` | List an organization's sandboxes. |
-| `upload_files` | Upload a small set of inline files or a base64-encoded ZIP. |
-| `list_files` | List files in a sandbox directory (`path` defaults to `/workspace`). |
-| `read_file` | Read a file from a sandbox (utf8 text, or base64 for small binaries). |
-| `list_urls` | List sandbox URLs for a sandbox. |
-| `create_url` | Expose a port as a sandbox URL (idempotent by port; `autoWake` and `public` default to false). |
-| `update_url` | Update a URL's port, autoWake, and/or public. |
-| `delete_url` | Delete a URL exposure. |
-| `list_mcps` | List MCP exposures configured for a sandbox (name, port, path, autoWake). |
-| `create_mcp` | Expose an MCP server running in a sandbox (idempotent by name; path defaults to `/mcp`). |
-| `update_mcp` | Update an MCP exposure's name, port, path, and/or autoWake. |
-| `delete_mcp` | Delete an MCP exposure. |
-| `list_sandbox_tools` | List tools exposed by MCP servers configured on a sandbox. |
-| `call_sandbox_tool` | Call a tool on a sandbox MCP server. |
-| `get_ssh_access` | Return temporary SSH credentials (60 minutes); idle auto-stop still applies. |
-| `revoke_ssh_access` | Revoke active SSH credentials for a sandbox. |
-| `run_command` | Run a shell command, waiting up to 120 seconds before returning handles for polling; idle auto-stop still applies. Sessions do not survive idle-stop — use Dockerfile/Compose or `set_sandbox_boot`. |
-| `set_sandbox_boot` | Register a bun-dev (or similar) command that starts now and after idle-stop. On Compose it runs after the stack; on a Dockerfile it replaces CMD. For host-only, create from `--source type=image`. |
-| `get_command` | Get a shell command's status and exit code. |
-| `get_command_logs` | Get paginated stdout and stderr for a shell command. |
-| `kill_command` | Interrupt a running shell command. |
-| `create_shell_session` | Create a sticky shell session that preserves cwd and environment between commands. |
-| `close_shell_session` | Close a sticky shell session. |
-| `update_sandbox` | Update the display name or idle-stop / auto-delete intervals (omit = no change; `null` = platform default). |
-| `wake_sandbox` | Start a stopped sandbox, or reset the idle-stop countdown if already running. |
-| `get_sandbox_status` | Get status, lifecycle deadlines, and optional features (tcp_bridge) without starting or touching activity. |
-| `stop_sandbox` | Stop a sandbox without deleting its files. |
-| `delete_sandbox` | Permanently delete a sandbox and its files. |
-| `publish_static` | Publish a static file set or ZIP to the CDN and return a durable `{adjective}-{adjective}-{noun}.static…` URL (does not create a sandbox). |
-| `publish_auto` | Inspect source (folder or ZIP) with the deploy agent and publish — CDN when pre-built static, otherwise a DeploymentSpec rendered to `Dockerfile.deploy` + `compose.deploy.yaml` and run with Compose. First deploy and replay use the same execute path. Same lifecycle flags as `create_sandbox`; minted URL defaults to public + auto-wake. Detected tests always run on Compose execution and are reported; `--require-verify` makes a failure `verify_failed` instead of deploying. On failure, inspect the kept sandbox and re-invoke with `--spec` to verify a DeploymentSpec on a clean box. Every terminal outcome stores the upload and returns authenticated `fileUrls`. Needs a usable compose-capable sandbox provider: with none, a call that plans fails with a not-configured error before planning, even for pre-built static files (use `publish_static` for those). |
-| `list_projects` | List first-class Projects (name, live URL, latest attempt). Distinct from `list_published_apps`. |
-| `get_project` | Get one project: name, slug, latest attempt, live deploy. |
-| `create_project` | Create an empty project (name only). No deploy until `publish_auto` ships source to this `projectId`. |
-| `update_project` | Rename a project. Pass `displayName` null or empty to clear the name. |
-| `list_project_deployments` | List ship attempts for a project, newest first. |
-| `get_project_deployment` | Get one deployment by id, including authenticated `fileUrls` when blobs were stored. |
-| `redeploy_project` | Ship stored source again. Omit `--deployment-id` to retry the last attempt that stored source. Pass `--deployment-id` for that version. Current project env is applied. New deployment row. |
-| `get_project_environment` | Get a project's stored environment (local entries, org opt-ins, bindings). Secret values withheld. |
-| `set_project_environment_selection` | Full-replace organization environment exports for a project (`environment` names + optional `bindings`). |
-| `set_project_environment_entry` | Create or replace one project-local variable or secret, by name (prefer CLI for secret values). |
-| `delete_project_environment_entry` | Delete one project-local variable or secret, by name. |
-| `unpublish_static` | Take a CDN-published static site offline so its public URL no longer serves files. |
-| `get_sandbox_environment` | Get a sandbox's environment: organization entries (selected + exportAs + overriddenByLocal), bindings, local entries, and whether it's running. |
-| `set_sandbox_environment_selection` | Full-replace organization exports (`environment` plain names + optional `bindings` remaps; omit bindings to clear remaps). |
-| `set_sandbox_environment_entry` | Create or replace one of a sandbox's own (local) variables or secrets, by name (prefer CLI for secret values). |
-| `delete_sandbox_environment_entry` | Delete one of a sandbox's own (local) variables or secrets, by name. |
-
-For example, create a sandbox, then expose a URL:
-
-```bash
-ghostdock create_sandbox --organization-id org_123 --display-name "Marketing site"
-ghostdock create_url --sandbox-id sandbox_123 --port 8080 --auto-wake true --public true
-```
-
-#### Environment in a sandbox
-
-A sandbox exports **nothing** by default (unless you boot from an organization snapshot or catalog
-image whose manifest supplies defaults). `environment` has three parts: `organization` (plain same-name opt-ins from the
-catalogue, see [`ghostdock env`](#ghostdock-env)), `bindings` (slot ← org entry remaps), and `local` (sandbox-only variables/secrets). A local entry overrides an
-organization export of the same name. Prefer the CLI when setting secret values so they are not
-pasted into the agent conversation.
-
-```bash
-# At create time, in one call:
-ghostdock create_sandbox --organization-id 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 get_sandbox_environment --sandbox-id sandbox_123
-ghostdock set_sandbox_environment_selection --sandbox-id sandbox_123 --environment '["VITE_API_URL"]' \
-  --bindings '[{"name":"DATABASE_URL","organization":"PROD_DATABASE_URL"}]'
-ghostdock set_sandbox_environment_selection --sandbox-id sandbox_123 --environment '[]'   # clears plain + remaps (omit bindings)
-ghostdock set_sandbox_environment_entry --sandbox-id sandbox_123 --name API_KEY --value sk_live --kind secret
-ghostdock delete_sandbox_environment_entry --sandbox-id sandbox_123 --name API_KEY
-```
-
-Values arrive as real environment variables, so read them with `process.env` / `$VAR` inside the
-sandbox. **Do not pass secrets in `run_command` strings** — the command text is retained and
-readable through `get_command_logs`. `get_sandbox_environment` reports every organization entry
-(selected + overriddenByLocal) and the sandbox's own local entries; `get_sandbox_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 `set_sandbox_environment_selection` /
-`set_sandbox_environment_entry` / `delete_sandbox_environment_entry` to restart a running sandbox
-instead).
-
-### Image tools
-
-Organization image catalog: OCI bookmarks (`add_image`), stored Dockerfiles
-(`add_image_dockerfile`), and refs currently in use on sandboxes. `list_images` and `get_image`
-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). `create_sandbox` with `--source '{"type":"image","id":"..."}'` boots a catalog
-row by id and applies its manifest (URLs + env) like an organization snapshot.
-
-| Tool | Purpose |
-| --- | --- |
-| `list_images` | Discovery catalog (not an allowlist): platform bases, bookmarks, Dockerfiles, in-use refs. |
-| `get_image` | One catalog row by id (OCI bookmark or Dockerfile from `list_images`). |
-| `add_image` | Bookmark an OCI ref; best-effort inspect caches label manifest. |
-| `add_image_dockerfile` | Store a Dockerfile; parses `ghostdock.*` LABEL lines into cached manifest. |
-| `update_image_dockerfile` | Replace Dockerfile text and re-parse manifest. |
-| `remove_image` | Delete a catalog row by id. |
-
-```bash
-ghostdock list_images --organization-id org_123
-ghostdock get_image --organization-id org_123 --image-id img_abc
-ghostdock add_image --organization-id org_123 --ref ghcr.io/acme/app:latest --label "Acme app"
-ghostdock add_image_dockerfile --organization-id org_123 --name my-stack --dockerfile "$(cat Dockerfile)"
-ghostdock create_sandbox --organization-id 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 sandbox_create`](#ghostdock-sandbox_create), not this command. Any OCI ref may still
-be passed as `{ type: "image", ref }` even when it does not appear in `list_images`. Catalog compose
-rows still boot via `{ type: "image", id }`.
-
-### `ghostdock publish_static`
-
-Publish a local directory or ZIP to the CDN (durable public URL, no sandbox):
-
-```bash
-ghostdock publish_static --organization-id org_123 ./dist
-ghostdock publish_static --organization-id org_123 --zip ./site.zip
-```
-
-MCP `publish_static` is for small inline payloads. Use this command for a real directory or large ZIP.
-
-### `ghostdock publish_auto`
-
-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 `create_sandbox`) 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 publish_auto --organization-id org_123 ./app
-ghostdock publish_auto --organization-id org_123 --auto-stop-interval-minutes -1 --zip ./app.zip
-ghostdock publish_auto --organization-id org_123 --project-id proj_123 ./app
-ghostdock publish_auto --organization-id org_123 ./app \
-  --environment '{"organization":["DATABASE_URL"],"local":[{"name":"API_KEY","value":"sk_live","kind":"secret"}]}'
-ghostdock publish_auto --organization-id org_123 ./app --spec '{"version":1,"run":{"kind":"static","outputDir":"."},"env":[]}'
-ghostdock publish_auto --organization-id org_123 --require-verify ./app
-ghostdock publish_auto --organization-id org_123 --sandbox-provider-id prov_123 ./app
-```
-
-MCP `publish_auto` is for small inline payloads. Use this command for a real directory or large ZIP.
-
-### `ghostdock sandbox_create`
-
-Create a sandbox from a local Dockerfile or Compose directory. The CLI zips the directory (or sends
-`--zip`) and the server builds it. MCP `create_sandbox` stays inline text only.
-
-```bash
-ghostdock sandbox_create --organization-id org_123 --kind dockerfile ./app
-ghostdock sandbox_create --organization-id org_123 --kind compose --zip ./stack.zip
-ghostdock sandbox_create --organization-id 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 sandbox_upload`
-
-`upload_files` is convenient for small payloads. For a local directory,
-multiple files, or a large ZIP, use the dedicated multipart upload command instead:
-
-```bash
-ghostdock sandbox_upload --sandbox-id sandbox_123 ./dist
-ghostdock sandbox_upload --sandbox-id sandbox_123 ./index.html ./assets
-ghostdock sandbox_upload --sandbox-id sandbox_123 --zip ./site.zip
-```
-
-Each positional path may be a file or directory. Directory contents are uploaded recursively,
-preserving their relative paths; a file is uploaded by its basename. A `sandbox_upload` call needs
-at least one path or `--zip`. Uploading to a stopped sandbox resumes it automatically.
-
-### `ghostdock env`
-
-Manage the environment variables and secrets an organization offers to its sandboxes and projects.
-A sandbox inherits nothing automatically — select the entries it needs on that sandbox.
-
-```bash
-ghostdock env list --organization org_123
-ghostdock env get VITE_API_URL --organization org_123
-ghostdock env set VITE_API_URL --organization org_123 --value https://api.example.com
-ghostdock env delete VITE_API_URL --organization 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 --organization 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 --organization 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 --organization 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.
-
-Add `--json` to `list`, `get` or `set` for machine-readable output. These commands wrap the
-`list_environment_variables`, `get_environment_variable`, `set_environment_variable` and
-`delete_environment_variable` 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.
-
-## 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_CREDENTIALS_PATH`   | Absolute path to the credentials file, overriding the default. | `./.ghostdock/credentials.json` (relative to the current working directory) |
-
-Example for local development against a Nuxt dev server:
-
-```bash
-ghostdock --base-url http://localhost:3000 login --wait
-# or
-GHOSTDOCK_BASE_URL=http://localhost:3000 ghostdock login --wait
-```
-
-## Credentials file
-
-Credentials are stored as JSON at `./.ghostdock/credentials.json` (relative to the directory the
-CLI is run from), with file permissions restricted to the owner (`0600`):
-
-```json
-{
-  "accessToken": "ext_at_...",
-  "refreshToken": "ext_rt_...",
-  "accessExpiresAt": "2026-07-30T12:00:00.000Z"
-}
-```
-
-**Add `.ghostdock/` to your project's `.gitignore`.** These are live tokens — never commit them.
-This repository's own `.gitignore` already ignores `.ghostdock/` for local development/testing of
-the CLI itself.
-
-Access tokens are short-lived (1 hour); the CLI refreshes them automatically using the refresh token
-(30-day rolling expiry) whenever a request gets a `401`. If both tokens are invalid or revoked (e.g.
-after `ghostdock logout` from another session), re-run `ghostdock login`.
-
-## Exit codes
-
-- `0` — success (including the default `login` after only printing the URL — approval is still
-  pending, that's expected).
-- `1` — failure: not logged in, session expired and unrefreshable, login denied/expired/timed out,
-  a missing/invalid tool flag, or a tool invocation error (e.g. not a member of the organization).