# ghostdock CLI reference Every command the `ghostdock` CLI ships, with its full description and flags. For how to install, log in and choose an organization, read [cli.md](cli.md). Concepts and workflows are in the built-in skills (`ghostdock skill list`). Binaries: `ghostdock`, `gdock`. Global flag `--base-url`: API origin (overrides GHOSTDOCK_BASE_URL and the built-in default). Global flag `--json`: Print the result as one JSON document on stdout, for scripts and agents. Without it, output is for people. ## `ghostdock completion` Tab completion for commands, flags, VM names, containers and organizations. ### `ghostdock completion bash` Print the bash completion script. `ghostdock completion install` adds it to ~/.bashrc (macOS: ~/.bash_profile). ``` ghostdock completion bash ``` ### `ghostdock completion fish` Print the fish completion script. `ghostdock completion install` writes it to ~/.config/fish/completions. ``` ghostdock completion fish ``` ### `ghostdock completion install` Set up tab completion for your shell: shows the one line it adds to the shell's startup file and asks first. Running it again changes nothing. Needs a global install: npx is not supported. ``` ghostdock completion install [shell] [flags] ``` | Argument | Description | | --- | --- | | `` | zsh, bash or fish. Default: your login shell ($SHELL). | | `--yes` | Add it without asking. | ### `ghostdock completion powershell` Print the powershell completion script. Add `ghostdock completion powershell | Out-String | Invoke-Expression` to your $PROFILE. ``` ghostdock completion powershell ``` ### `ghostdock completion zsh` Print the zsh completion script. `ghostdock completion install` adds it to ~/.zshrc. ``` ghostdock completion zsh ``` ## `ghostdock docker` Docker over the private network: a VM's Docker engine from this machine. ### `ghostdock docker context` Point Docker at a VM's Docker engine over the private network: plain `docker` and `docker compose` then run there. Creates (or updates) the Docker context ghostdock-- for tcp://..ghostdock.internal:2376 with a client certificate of this machine's device, and makes it the current context. Needs `ghostdock network connect` first, and Docker's CLI. The certificate lives 30 days; `network connect` and this command renew it with 10 days left. An expired certificate fails Docker's TLS handshake with Docker's own error: run this command again. Docker's `no such host` on a ghostdock.internal address means this machine is not connected: run `ghostdock network connect`. After an organization rename the old name stops resolving: run it again to update the host. ``` ghostdock docker context [flags] ``` | Argument | Description | | --- | --- | | `` | VM name, from `network vms`. Required. | | `--org ` | Organization id, slug or name, from `ghostdock organization list` (default: GHOSTDOCK_ORG, then `ghostdock organization use`). | | `--use` | Make it the current Docker context (`docker context use`). `--no-use` only creates or updates it. Default: `true`. | ## `ghostdock domain` ### `ghostdock domain attach` Attach a custom domain to a provider. The organization’s stored domain keeps its certificate; a new one is added. Owner or admin. A domain the provider had is detached and kept. Returns the DNS records to create; then call domain check. certificatePlan says what it costs: reuse (its certificate, no order) or order (a new certificate, with allowance). A domain another provider uses is refused: domain detach it there first. ``` ghostdock domain attach --provider [flags] ``` | Argument | Description | | --- | --- | | `` | Custom domain, such as boxes.example.com (domain list). Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--provider ` | Provider name or id, from provider list. Required. | MCP tool: `domain_attach`. ### `ghostdock domain check` Check the DNS records of an attached custom domain against its provider. Owner or admin. Once they point at the provider, a stored certificate valid for more than 7 days is served at once; otherwise Let’s Encrypt is asked for one (status pending_ssl, then active). Call again until checks pass. ``` ghostdock domain check [flags] ``` | Argument | Description | | --- | --- | | `` | Custom domain, such as boxes.example.com (domain list). Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `domain_check`. ### `ghostdock domain delete` Delete a custom domain and throw its certificate away. Owner or admin. Adding it again orders a new certificate, which counts toward Let’s Encrypt’s 5 per 168 h (see allowance in domain list). A domain a provider uses is refused unless confirmInUse: then it is detached first and that provider’s VM URLs stop. ``` ghostdock domain delete [flags] ``` | Argument | Description | | --- | --- | | `` | Custom domain, such as boxes.example.com (domain list). Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--confirm-in-use` | Required when a provider uses the domain: detaches it from that provider, then deletes it. | MCP tool: `domain_delete`. ### `ghostdock domain detach` Detach a custom domain from the provider that uses it. Owner or admin. Its VM URLs on that provider stop; the domain and its certificate stay, ready to be attached again without a new certificate. ``` ghostdock domain detach [flags] ``` | Argument | Description | | --- | --- | | `` | Custom domain, such as boxes.example.com (domain list). Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `domain_detach`. ### `ghostdock domain list` List the organization’s custom domains and their certificates. Each domain is used by a provider or kept unused. Each has provider (null: unused, since unusedSince, its certificate kept), certificate (expiry), renewal (automatic; once_more: unused, renewed once more; stopped: unused and left to expire; manual: uploaded), renewsAt, lastIssuedAt, lastError, and allowance: how many new certificates Let’s Encrypt still issues for its name now (5 per 168 h), with nextAt when none is left. ``` ghostdock domain list [flags] ``` | Argument | Description | | --- | --- | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `domain_list`. ## `ghostdock env` Manage organization environment variables and secrets. ### `ghostdock env delete` Delete a variable or secret. ``` ghostdock env delete [flags] ``` | Argument | Description | | --- | --- | | `` | Environment variable name. Required. | | `--org ` | Organization id, slug or name, from `ghostdock organization list` (default: GHOSTDOCK_ORG, then `ghostdock organization use`). | MCP tool: `env_delete`. ### `ghostdock env get` Print one variable value in full (secrets cannot be read). ``` ghostdock env get [flags] ``` | Argument | Description | | --- | --- | | `` | Environment variable name. Required. | | `--org ` | Organization id, slug or name, from `ghostdock organization list` (default: GHOSTDOCK_ORG, then `ghostdock organization use`). | MCP tool: `env_get`. ### `ghostdock env list` List variables and secrets. ``` ghostdock env list [flags] ``` | Argument | Description | | --- | --- | | `--org ` | Organization id, slug or name, from `ghostdock organization list` (default: GHOSTDOCK_ORG, then `ghostdock organization use`). | MCP tool: `env_list`. ### `ghostdock env set` Create or replace a variable or secret. ``` ghostdock env set [flags] ``` | Argument | Description | | --- | --- | | `` | Environment variable name. Required. | | `--org ` | Organization id, slug or name, from `ghostdock organization list` (default: GHOSTDOCK_ORG, then `ghostdock organization use`). | | `--value ` | Value to store. | | `--value-stdin` | Read the value from stdin — keeps secrets out of shell history. | | `--secret` | Shorthand for --kind secret. Required when creating a secret. | | `--kind ` | variable or secret. Required when creating; on an update, omit to keep the existing kind or pass the other to convert. | | `--comment ` | Note about what this value is for. | MCP tool: `env_set`. ## `ghostdock login` Sign in and store a device access token for this machine and server (~/.config/ghostdock/servers/). Prints a URL to approve in the browser and waits for the approval. Agents, whose output is only seen once a command ends, run `login start`, show the URL to the user, then run `login finish`. ``` ghostdock login [flags] ``` | Argument | Description | | --- | --- | | `--timeout ` | Max seconds to wait for approval (default 300). | | `--org ` | Set this organization (id or slug) as the default once logged in. | | `--code ` | Same as `login finish --code`. | | `--wait` | No effect: waiting is the default. Kept for older scripts. | ### `ghostdock login finish` Agent step 2: finish the login `login start` began. Waits until the user approves it in the browser (done at once when they already have); never starts a new login. ``` ghostdock login finish [flags] ``` | Argument | Description | | --- | --- | | `--timeout ` | Max seconds to wait for approval (default 300). | | `--org ` | Set this organization (id or slug) as the default once logged in. | | `--code ` | Redeem the one-time paste code the browser shows ("Having trouble? Show code") instead of waiting. | ### `ghostdock login start` Agent step 1: print the sign-in URL and exit. Show the URL to the user, then run `login finish`. Run again before finishing, it prints the same URL. ``` ghostdock login start ``` ## `ghostdock logout` Revoke the device session and remove stored credentials. ``` ghostdock logout ``` ## `ghostdock network` The private network: reach your VMs by address and name from this machine. ### `ghostdock network connect` Put this machine into the private network through one provider: WireGuard and split DNS. Also re-arms a paused device: with the tunnel up and nothing changed, without sudo. ``` ghostdock network connect [provider] [flags] ``` | Argument | Description | | --- | --- | | `` | Provider name or id. Omit for the organization's default provider (else the platform default). Only its VMs are reachable; connecting through another replaces the connection. | | `--org ` | Organization id, slug or name, from `ghostdock organization list` (default: GHOSTDOCK_ORG, then `ghostdock organization use`). | ### `ghostdock network devices` Your devices in the private network. ``` ghostdock network devices ``` ### `ghostdock network devices remove` Remove one of your devices from the private network. ``` ghostdock network devices remove ``` | Argument | Description | | --- | --- | | `` | Device id, from `network devices`. Required. | ### `ghostdock network disconnect` Take this machine out of the private network, and remove split DNS an earlier connection left (macOS). ``` ghostdock network disconnect ``` ### `ghostdock network status` Whether this machine is connected, through which provider, and as which device. ``` ghostdock network status ``` ### `ghostdock network vms` VMs of an organization with their private addresses and names, and which are reachable through the current connection. ``` ghostdock network vms [flags] ``` | Argument | Description | | --- | --- | | `--org ` | Organization id, slug or name, from `ghostdock organization list` (default: GHOSTDOCK_ORG, then `ghostdock organization use`). | ## `ghostdock organization` Organizations you belong to. ### `ghostdock organization current` Show which organization commands use, and where it comes from. ``` ghostdock organization current [flags] ``` | Argument | Description | | --- | --- | | `--org ` | Check what this --org would resolve to. | ### `ghostdock organization list` List the organizations you belong to, with their ids and slugs. ``` ghostdock organization list ``` MCP tool: `organization_list`. ### `ghostdock organization use` Set the default organization for commands run without --org (in every directory). ``` ghostdock organization use [org] [flags] ``` | Argument | Description | | --- | --- | | `` | Organization id or slug. | | `--clear` | Remove the default organization. | ## `ghostdock project` Deployable projects, their deployments and environment. ### `ghostdock project create` Create an empty project. Nothing is deployed until project publish. ``` ghostdock project create --display-name [flags] ``` | Argument | Description | | --- | --- | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--display-name ` | Project name. Required. | MCP tool: `project_create`. ### `ghostdock project delete` Permanently delete a project and everything it runs and stores. Every VM its deployments ran on goes (locked containers too), with its live URL, its CDN site, the stored uploads and generated files, its deployment history and its environment. Cannot be undone. ``` ghostdock project delete [flags] ``` | Argument | Description | | --- | --- | | `` | Project id, from project list (project publish returns it too). Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `project_delete`. ### `ghostdock project deployment` Deployments of a project. ### `ghostdock project deployment get` Get one deploy attempt, with links to its stored files. fileUrls are authenticated GET paths for source.zip and generated Compose files. ``` ghostdock project deployment get --project-id [flags] ``` | Argument | Description | | --- | --- | | `` | Deployment id, from project deployment list. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--project-id ` | Project id, from project list (project publish returns it too). Required. | MCP tool: `project_deployment_get`. ### `ghostdock project deployment list` List a project’s deploy attempts, newest first. ``` ghostdock project deployment list [flags] ``` | Argument | Description | | --- | --- | | `` | Project id, from project list (project publish returns it too). Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `project_deployment_list`. ### `ghostdock project env` Environment a project exports. ### `ghostdock project env delete` Delete one of a project’s own variables or secrets. ``` ghostdock project env delete --project-id [flags] ``` | Argument | Description | | --- | --- | | `` | Environment variable name, e.g. DATABASE_URL. Letters, digits and underscores only. Case-sensitive; stored exactly as provided. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--project-id ` | Project id, from project list (project publish returns it too). Required. | MCP tool: `project_env_delete`. ### `ghostdock project env get` Get a project’s stored environment. Local entries (secret values withheld), organization opt-ins and bindings, applied on every deploy. platformEntries lists the variables Ghostdock gives every container of the VM a deploy runs in, so dev servers accept its URL host names (read the vm skill (`ghostdock skill get vm`)): for the VM serving the project, else the provider a deploy without providerId uses; none when the project is served from the CDN. overriddenBy is set when a project entry of the same name replaces one; a compose file’s own environment value wins inside that container. GHOSTDOCK_* names are reserved. ``` ghostdock project env get [flags] ``` | Argument | Description | | --- | --- | | `` | Project id, from project list (project publish returns it too). Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `project_env_get`. ### `ghostdock project env select` Replace the organization entries a project exports. Full replace: environment is the whole list ([] clears it), and omitting bindings clears the remaps. Read the environment skill (`ghostdock skill get environment`). ``` ghostdock project env select --environment [flags] ``` | Argument | Description | | --- | --- | | `` | Project id, from project list (project publish returns it too). Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--environment ` | Organization catalogue entry names to export under their own names. (JSON array) Required. | | `--bindings ` | Slot-centric org bindings. Omit to clear existing remaps. (JSON array) | MCP tool: `project_env_select`. ### `ghostdock project env set` Create or replace one of a project’s own variables or secrets. It overrides an organization entry or platform variable of the same name (GHOSTDOCK_* names are reserved). Prefer the CLI for secret values so they stay out of the conversation. ``` ghostdock project env set --project-id --value --kind [flags] ``` | Argument | Description | | --- | --- | | `` | Environment variable name, e.g. DATABASE_URL. Letters, digits and underscores only. Case-sensitive; stored exactly as provided. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--project-id ` | Project id, from project list (project publish returns it too). Required. | | `--value ` | The value to store. A secret value can be replaced later but never read back. Required. | | `--kind ` | "variable" or "secret". A secret value can be replaced but never read back. Required. | | `--comment ` | Optional note shown with the entry, e.g. what it is for. | MCP tool: `project_env_set`. ### `ghostdock project get` Get a project with its latest attempt and live deployment. latestDeploymentId includes failures; liveDeploymentId / liveUrl is the success that serves the public URL. ``` ghostdock project get [flags] ``` | Argument | Description | | --- | --- | | `` | Project id, from project list (project publish returns it too). Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `project_get`. ### `ghostdock project list` List an organization’s projects. A project owns its environment, deployment history and live URL. site list lists sites instead. ``` ghostdock project list [flags] ``` | Argument | Description | | --- | --- | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `project_list`. ### `ghostdock project publish` Inspect local source with the deploy agent and publish to the CDN or a VM. ``` ghostdock project publish [path] [flags] ``` | Argument | Description | | --- | --- | | `--org ` | Organization id, slug or name, from `ghostdock organization list` (default: GHOSTDOCK_ORG, then `ghostdock organization use`). | | `--project-id ` | Existing project id. Omit to create a project. | | `--replan` | Force a new planner run even when the stored spec still matches. | | `--require-verify` | Fail the deploy (verify_failed) when detected tests fail. Default false: tests still run and are reported. | | `--spec ` | JSON DeploymentSpec to execute on a fresh VM instead of planning. Mutually exclusive with --replan. | | `--display-name ` | Optional display name. | | `--tag ` | Optional caller tag (git SHA or free-form label) stored on the deployment. | | `--lifecycle ` | Same as `vm up`: ephemeral, auto_delete (default) or keep. | | `--idle-stop-minutes ` | Same as `vm up`. Omit for the 20-minute default. Pass -1 to keep it running. 0 is rejected. | | `--auto-delete-days ` | Same as `vm up`: days stopped before the record is deleted (1–365). Omit for the 14-day default. | | `--resources ` | Same as `vm up`: JSON { cpu, memoryGiB, diskGiB }. | | `--environment ` | Same as `vm up --environment`: JSON { organization, bindings, local }. Required after awaiting_configuration. | | `--auto-wake ` | Whether the published URL wakes a stopped VM, as `vm url set --wake`. Default true. | | `--public ` | Whether the published URL is public (true) or for the organization (false), as `vm url set --access`. Default true; a publish never lowers a URL to organization. | | `--provider ` | Same as `vm up`: provider name or id (omit for the organization default). | | `--zip ` | Local ZIP of the source tree. | | `` | File or directory to publish (additional paths are allowed). | MCP tool: `project_publish`. ### `ghostdock project redeploy` Deploy a project’s stored source again, with its current environment. No new upload. Omit deploymentId to retry the last attempt that stored source. Same outcomes and settings as project publish; read the publishing skill (`ghostdock skill get publishing`). ``` ghostdock project redeploy [flags] ``` | Argument | Description | | --- | --- | | `` | Project id, from project list (project publish returns it too). Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--deployment-id ` | Ship this version’s stored upload and spec. Omit to retry the last attempt that stored source. | | `--require-verify` | When true, a failing verify step stops the deploy (verify_failed) and tears the VM down. Default false. | | `--tag ` | Optional caller tag stored on the new deployment. Metadata only. | | `--resources ` | Compute sizing. For image/dockerfile/compose: layered on platform defaults when omitted. For snapshot: optional override applied via resize after create. (JSON object) | | `--idle-stop-minutes ` | Minutes of inactivity before the platform worker idle-stops the VM. -1: never stops for inactivity. 0 is rejected. Omit for the platform default. Provider-native timers are optional backup. A Container host in which no container runs also sleeps 5 minutes after the last one stopped; a Server (e.g. `vm up headless`) stops by this time alone. Timers and cron jobs are not activity: a Server whose work is only timers or cron jobs takes -1. | | `--lifecycle ` | What happens when the VM stops. ephemeral: the VM and its disk are deleted, and it cannot be started again; a stop by the platform (host maintenance) keeps it. auto_delete (default): a stop keeps the disk, and the record goes autoDeleteDays after it. keep: a stop keeps the disk, and the record is never removed automatically. | | `--auto-delete-days ` | Days the VM stays stopped before the platform worker deletes the record (1–365). Omit for the platform default (14). Makes the VM auto_delete; not with keep or ephemeral. A container a person locked holds it. | | `--provider ` | Provider name or id from provider list (not the provider kind). Omit to use the organization default (the org choice, else the platform default); if that provider lacks a capability this create needs, the first listed provider that accepts new VMs and has it is used. When no provider fits, the call fails with a not-configured error. | | `--environment ` | Environment to give this VM. organization: names of organization entries (from env list) to export under their own names. bindings: remap org entries onto slot names ({ name: slot, organization: orgEntryName }). local: VM-only variables/secrets to create with the VM (kind required for each). Both land as ordinary process environment variables ($NAME / process.env.NAME); a local entry overrides an organization entry of the same name. When booting from an organization snapshot, omit organization/bindings/local to keep manifest env defaults, but still supply every name in requiredEnvironment (via organization, bindings, or local). Otherwise a VM gets nothing unless listed here. (JSON object) | | `--auto-wake` | Same as urls[].autoWake on vm up. Default true for the minted URL. | | `--public` | Whether the minted URL is public (anyone) or, false, organization (members only). Default true. | MCP tool: `project_redeploy`. ### `ghostdock project update` Rename a project. ``` ghostdock project update --display-name [flags] ``` | Argument | Description | | --- | --- | | `` | Project id, from project list (project publish returns it too). Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--display-name ` | New name. Null or empty clears it. Required. | MCP tool: `project_update`. ## `ghostdock provider` Providers of an organization. ### `ghostdock provider connect` Start connecting your own server to Ghostdock as an Incus host or a Docker host. kind is incus (VMs as system containers in an Incus project of their own) or docker (VMs as containers next to the server’s Docker, with Sysbox). Owner or admin. Returns the new provider and its join: the secret setupCommand to run on that server as root, valid for one hour and one join. Then call provider verify. To finish an incomplete setup, get a new command with provider new-join instead of connecting again. Read the host-setup skill (`ghostdock skill get host-setup`) first. ``` ghostdock provider connect [flags] ``` | Argument | Description | | --- | --- | | `` | incus: VMs as system containers in an Incus project on the server (needs Incus 7, Linux 6.12, a ZFS or Btrfs pool). docker: VMs as containers next to Docker, with Sysbox. Required. | | `--name ` | Name for the new provider. Optional. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `provider_connect`. ### `ghostdock provider disconnect` Disconnect one of the organization’s own providers. Owner or admin. Fails while VMs or volumes still use it (volume delete them first). If organization snapshots live on it, the first call fails: pass confirmLinkedDeletion to delete them permanently. A Docker host that is not connected cannot delete its VMs and volumes: the first call fails, and confirmLinkedDeletion removes them from Ghostdock (whatever is still on the machine stays there). Also frees its custom domain; a default provider falls back to the platform default. ``` ghostdock provider disconnect [flags] ``` | Argument | Description | | --- | --- | | `` | Provider name or id, from provider list. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--confirm-linked-deletion` | Required when this provider still has organization snapshots, or VMs or volumes on a Docker host that is not connected. Permanently deletes those snapshots and removes those VMs and volumes from Ghostdock, then disconnects. | MCP tool: `provider_disconnect`. ### `ghostdock provider list` List the providers an organization can create VMs on. Includes its own connected providers and the platform providers it may use, in fallback order. Use an item id as provider. Only items with acceptsNewVms true take new VMs; an own provider stays incomplete until customDomain.status is active. defaultProviderId is the effective default. shadows and shadowed say an organization provider hides a platform provider of the same name, ignoring case. hostFolders are the folders a Docker or Incus host’s owner listed at setup (name, original path, readOnly), which volume create hostFolder picks from; null when the host predates host folders. Read the vm skill (`ghostdock skill get vm`) for the details. ``` ghostdock provider list [flags] ``` | Argument | Description | | --- | --- | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `provider_list`. ### `ghostdock provider new-join` Get a new setup command for a Docker or Incus host that is not connected. For when the first expired or the server was set up again. Owner or admin. Refused while the server is connected. Read the host-setup skill (`ghostdock skill get host-setup`). ``` ghostdock provider new-join [flags] ``` | Argument | Description | | --- | --- | | `` | Provider name or id, from provider list. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `provider_new_join`. ### `ghostdock provider rename` Rename one of the organization’s own providers. Owner or admin. Platform providers cannot be renamed; names must be unique in the organization, ignoring case. ``` ghostdock provider rename --name [flags] ``` | Argument | Description | | --- | --- | | `` | Provider name or id, from provider list. Required. | | `--name ` | New name, unique in the organization ignoring case. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `provider_rename`. ### `ghostdock provider set-address` Set the address an organization’s Docker or Incus host is reached at. For a machine people reach at another address than the one its agent connects from: behind NAT, a second address, or a dynamic DNS name. Owner or admin. An IPv4 address makes the custom domain’s traffic record an A record, an IPv6 address AAAA, a host name CNAME; provider list shows it as address (source set). null goes back to the connection’s address (source connection). Then check the domain (domain check). ``` ghostdock provider set-address --address [flags] ``` | Argument | Description | | --- | --- | | `` | Provider name or id, from provider list. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--address ` | An IPv4 or IPv6 address or a host name, such as 203.0.113.7 or home.example.net. null: the address the host connects from. Required. | MCP tool: `provider_set_address`. ### `ghostdock provider set-auto-update` Turn automatic updates of a provider on or off. Owner or admin. On (the default), it takes each new release by itself a day after it is published, the same way as provider update. Only for providers that provider status gives a release. ``` ghostdock provider set-auto-update --enabled [flags] ``` | Argument | Description | | --- | --- | | `` | Provider name or id, from provider list. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--enabled` | true to update automatically, false to update only by hand. Required. | MCP tool: `provider_set_auto_update`. ### `ghostdock provider set-default` Set the provider used when a create omits provider. Applies to vm up, project publish and project redeploy. Pass an own connected provider or a platform provider that accepts new VMs; pass null (or platformDefaultProviderId) to follow the platform default. With decline, answers "no" to a Docker or Incus host’s setup question (setup step default in provider status): stored, so it is not asked again, and the default stays. Owner or admin. ``` ghostdock provider set-default [flags] ``` | Argument | Description | | --- | --- | | `` | Provider name or id from provider list (own or platform), or null to follow the platform default. Passing platformDefaultProviderId also follows the platform default; it is never pinned. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--decline` | Do not make this Docker or Incus host the default, and do not ask again (its setup step default is then done). The default stays as it is. | MCP tool: `provider_set_default`. ### `ghostdock provider status` Show how a provider is doing: what is wrong now and where its release stands. failing lists the checks failing now, oldest first, with the VMs each affects; blocking ones stop new VMs once they have lasted. release says the current and latest release, its state (current, outdated, unsupported, blocked, unknown), canUpdate and autoUpdate. Kinds that report less leave failing empty and release null: platform providers. ``` ghostdock provider status [flags] ``` | Argument | Description | | --- | --- | | `` | Provider name or id, from provider list. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `provider_status`. ### `ghostdock provider update` Update a provider to its newest release. Owner or admin. Only when provider status says canUpdate (today: Docker and Incus hosts). Returns the target version and updateId at once; the host downloads the release and replaces its own containers or instances in a minute or two, and VMs keep running. While it runs, provider status shows release.update with its step (download, replace, health) and progress. If the new release is not healthy within 5 minutes, it returns to the old one and provider status lists a docker-update or incus-update failure. provider update-list says how it ended; provider update-log has its log. ``` ghostdock provider update [flags] ``` | Argument | Description | | --- | --- | | `` | Provider name or id, from provider list. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `provider_update`. ### `ghostdock provider update-list` List a provider’s last 20 updates, newest first. Each says by hand (with who) or automatic, from and to which version, when, and how it ended (running, updated, rolled_back, failed, lost) with the reason. hasLog says whether provider update-log has its log (hosts on a release with update logs). Today: Docker and Incus hosts. ``` ghostdock provider update-list [flags] ``` | Argument | Description | | --- | --- | | `` | Provider name or id, from provider list. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `provider_update_list`. ### `ghostdock provider update-log` Show one of a provider’s updates with the host’s log of it. The log says what the host did: the download, the swap, the new release’s health report, and a rollback’s reason. A long log keeps its start and its end. ``` ghostdock provider update-log [flags] ``` | Argument | Description | | --- | --- | | `` | Provider name or id, from provider list. Required. | | `` | The update id, from provider update-list or provider update. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `provider_update_log`. ### `ghostdock provider verify` Check or finish connecting a Docker or Incus host. Owner or admin. Runs the server's self-check, and a failure names what is wrong; with an active domain it also tries a VM URL from outside (reach). Read the host-setup skill (`ghostdock skill get host-setup`). ``` ghostdock provider verify [flags] ``` | Argument | Description | | --- | --- | | `` | Provider name or id, from provider list. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `provider_verify`. ## `ghostdock registry` Log in to the organization container registry. ### `ghostdock registry credentials` Print registry host, username, and the one-hour password. ``` ghostdock registry credentials [flags] ``` | Argument | Description | | --- | --- | | `--org ` | Organization id, slug or name, from `ghostdock organization list` (default: GHOSTDOCK_ORG, then `ghostdock organization use`). | | `--provider ` | Provider name or id. Omit for the provider `vm up` would pick (org default, else platform default, else the first that fits). | MCP tool: `registry_credentials`. ### `ghostdock registry login` Fetch a one-hour password and run docker login --password-stdin. ``` ghostdock registry login [flags] ``` | Argument | Description | | --- | --- | | `--org ` | Organization id, slug or name, from `ghostdock organization list` (default: GHOSTDOCK_ORG, then `ghostdock organization use`). | | `--provider ` | Provider name or id. Omit for the provider `vm up` would pick (org default, else platform default, else the first that fits). | ## `ghostdock site` Sites: static files on the CDN. ### `ghostdock site delete` Permanently delete a site and its files. Its files leave the CDN, its URL answers 404, and its name is free again. A project’s deployment is the project’s: delete the project instead. ``` ghostdock site delete [flags] ``` | Argument | Description | | --- | --- | | `` | Site id: the slug in the public URL, as returned by site publish or site list. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `site_delete`. ### `ghostdock site list` List the sites of an organization, last published first, with their URLs. owner is the identity that created a site (its token’s name, and its VM’s name for a VM’s identity); null for an ordinary site. bytes is what its files take on the CDN; null until measured. A site is static files on the CDN; each has a siteId to pass to site publish (to republish into it), site delete and site release. A token of reach own sees only its own sites. ``` ghostdock site list [flags] ``` | Argument | Description | | --- | --- | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `site_list`. ### `ghostdock site publish` Publish a site: local files, a directory or a ZIP, to the CDN. Without --site-id it creates a new site with its own URL; with it, it republishes into that site, keeping its URL. ``` ghostdock site publish [path] [flags] ``` | Argument | Description | | --- | --- | | `--org ` | Organization id, slug or name, from `ghostdock organization list` (default: GHOSTDOCK_ORG, then `ghostdock organization use`). | | `--site-id ` | Republish into this site (its id from site list or an earlier publish), keeping its URL: its files are replaced in place, never offline. Omit to create a new site. | | `--display-name ` | Optional site display name. | | `--zip ` | Local ZIP file to publish. | | `` | File or directory to publish (additional paths are allowed). | MCP tool: `site_publish`. ### `ghostdock site release` Release a site from the identity that created it. The owner is a VM’s identity or a token of reach own. It becomes an ordinary site of the organization and keeps its URL and files: the owner can no longer see or manage it, and it no longer counts against the owner’s budget. A member, or the owner itself. ``` ghostdock site release [flags] ``` | Argument | Description | | --- | --- | | `` | Site id: the slug in the public URL, as returned by site publish or site list. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `site_release`. ## `ghostdock skill` List and read Agent Skills (same catalog as MCP skill://index.json). ### `ghostdock skill get` Print one SKILL.md (URI from the discovery index, or a skill name). ``` ghostdock skill get ``` | Argument | Description | | --- | --- | | `` | skill:// URI, org/name, or skill name. Required. | MCP tool: `skill_get`. ### `ghostdock skill list` List the Agent Skills discovery index. ``` ghostdock skill list ``` MCP tool: `skill_list`. ## `ghostdock snapshot` VM snapshots. ### `ghostdock snapshot create` Save a VM’s filesystem as a reusable organization snapshot. The VM must be stopped, unless stopAndResume. Captures its URLs and environment into a manifest (secrets as required, without values). Waits up to ~120 seconds; if still pending it returns timedOut, then poll snapshot get. Setting secret values here is allowed; prefer the Ghostdock CLI so they stay out of the conversation. ``` ghostdock snapshot create --name [flags] ``` | Argument | Description | | --- | --- | | `` | VM name (e.g. quiet-harbor) or id, from vm list or vm up. Names are unique within the organization. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--name ` | Snapshot name, unique in the organization. Required. | | `--stop-and-resume` | When the VM is running: stop it, snapshot, then start it again. Without this it must already be stopped. | | `--include-secret-values ` | Names of VM-local secrets whose values to embed in the snapshot. Organization secrets cannot be copied. (JSON array) | | `--manifest ` | Replaces the captured URLs and environment entirely (no merge). Secret values are stored encrypted. (JSON object) | MCP tool: `snapshot_create`. ### `ghostdock snapshot delete` Permanently delete an organization snapshot (provider artifact and record). ``` ghostdock snapshot delete [flags] ``` | Argument | Description | | --- | --- | | `` | Snapshot id from snapshot list (the provider snapshot name), its database id, or its name. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `snapshot_delete`. ### `ghostdock snapshot get` Get one snapshot with its manifest and required environment, URLs and MCPs. Returns a redacted manifest with requiredEnvironment / requiredUrls / requiredMcps. Poll it after snapshot create while status is pending. ``` ghostdock snapshot get [flags] ``` | Argument | Description | | --- | --- | | `` | Snapshot id from snapshot list (the provider snapshot name), its database id, or its name. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `snapshot_get`. ### `ghostdock snapshot list` List the snapshots an organization can boot VMs from. Each item has status (pending, active, error), the provider that holds it (providerId; boot it there), vmCount, and a redacted manifest with requiredEnvironment / requiredUrls / requiredMcps. ``` ghostdock snapshot list [flags] ``` | Argument | Description | | --- | --- | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | MCP tool: `snapshot_list`. ### `ghostdock snapshot update-manifest` Replace a snapshot’s manifest (URLs, environment, MCPs). Does not change the snapshot itself. Secret values in the body are stored encrypted; the response is redacted. Setting secret values here is allowed; prefer the Ghostdock CLI so they stay out of the conversation. ``` ghostdock snapshot update-manifest --manifest [flags] ``` | Argument | Description | | --- | --- | | `` | Snapshot id from snapshot list (the provider snapshot name), its database id, or its name. Required. | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--manifest ` | The new manifest; replaces the stored one. Secret values are stored encrypted. (JSON object) Required. | MCP tool: `snapshot_update_manifest`. ## `ghostdock ssh-key` SSH keys of your account, for logging in to Servers. ### `ghostdock ssh-key add` Add an SSH public key to your account, for logging in to Servers. Without a file, asks which key of this machine to add, or generates a new one. Then `vm ssh` uses it, and plain ssh, scp, rsync and VS Code log in to the Servers of every organization you belong to; `vm ssh --print` shows the command and `--config` the block for ~/.ssh/config. ed25519, ecdsa, or RSA of at least 3072 bits; only the public key is sent. ``` ghostdock ssh-key add [file] [flags] ``` | Argument | Description | | --- | --- | | `` | The public key file, e.g. ~/.ssh/id_ed25519.pub, or - to read it from stdin. Omit to choose one, or to generate a new one. | | `--name ` | A name for the key, e.g. laptop. Default: the key's comment. | MCP tool: `ssh_key_add`. ### `ghostdock ssh-key delete` Remove an SSH key from your account. Logins with it stop at once. ``` ghostdock ssh-key delete ``` | Argument | Description | | --- | --- | | `` | Key id, from ssh-key list. Required. | MCP tool: `ssh_key_delete`. ### `ghostdock ssh-key list` List the SSH public keys of your account. With one of them, ssh --@ (or ----@) logs in to a Server of any of your organizations, without vm ssh; vm ssh --print answers that command as keyCommand, with what a client needs to use it. ``` ghostdock ssh-key list ``` MCP tool: `ssh_key_list`. ## `ghostdock template` ### `ghostdock template create` Save a VM create request as a template of the organization. Its members and agents make it with `ghostdock vm up `. spec is what vm up takes without the organization’s own things: system (what boots: headless, desktop, container-host or an OS image ref labelled ghostdock.os=true; omitted: the create’s default, a Container host when the template runs something, a headless Server when it does not), source (what runs on it: an image ref, Dockerfile, Compose files or a Compose reference; no snapshot), at least one of the two, and defaults (resources, lifecycle, restart, urls, mcps). Environment values stay out: a template that needs some declares them as ghostdock.env labels. A name the platform has too is allowed: the answer says shadows true, and the organization’s template wins for its members. ``` ghostdock template create --name --title --spec [flags] ``` | Argument | Description | | --- | --- | | `--org ` | Organization id, slug or name, from organization list. A name works when only one of your organizations has it. Ids survive renames; slugs and names change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organization use`. | | `--name ` | Short name, unique in the organization: lower-case words joined by hyphens, e.g. postgres-pgadmin. Required. | | `--title ` | Title on the tile. Required. | | `--description ` | What it is for, in a sentence or two. | | `--instructions ` | Setup instructions in Markdown: what to prepare before a create (credentials, where to find them) and how to use the VM. Shown in Create VM, the gallery and `template get`; raw HTML is shown as text. | | `--listed` | Offered in Create VM and template list (default true). false: a building block used by name only (vm up, another template), still shown on the templates page. | | `--icon ` | An Iconify class the app bundles (i-simple-icons-postgresql, i-lucide-database) or an https image URL. Omit for the default icon. | | `--spec ` | The create request: { system?, source?, resources?, idleStopMinutes?, lifecycle?, autoDeleteDays?, restart?, urls?, forwards?, mcps? }, the same fields vm up takes; system or source or both (container-host needs a source). A URL’s or forward’s target names a Compose service of the source, never a container. (JSON object) Required. | MCP tool: `template_create`. ### `ghostdock template delete` Delete a template of the organization by its name. VMs made from it keep running; a platform template it shadowed answers to the name again. ``` ghostdock template delete