ghost CLI reference

ghost is the Gigahost command-line client. It prints results for reading, in tables and with colors on a terminal, and as JSON when you pass --json, so the same commands serve interactive use and automation.

Install

curl -fsSL https://api.gigahost.cloud/install/ghost.sh | sh
ghost --version

One command installs ghost for you, without root, as ~/.local/bin/ghost. ghost --version prints the installed release. Run the same command to update.

• The released ghost is one statically linked x86-64 Linux binary: it needs no system libraries, so it runs on any x86-64 Linux distribution, old or new.
• It is published on a signed release channel. The script refuses the release unless the manifest’s Ed25519 signature matches the release public key embedded in the script and the archive’s SHA-256 matches the signed manifest.
• The script needs curl, jq, and openssl. It checks the signature with OpenSSL 3, or with python3 on systems whose OpenSSL is older, such as Ubuntu 20.04, Debian 11, and RHEL 8; with neither, it stops and says so.
• It tells you if ~/.local/bin is not on your PATH.
• Run it as root to install for every user under /usr/local, or set GIGAHOST_INSTALL_PREFIX to another prefix.

Keep it up to date

ghost names its release with every request. Gigahost serves every release for at least 90 days after it was built (a release’s name starts with its build time, such as 20261010T120000Z-…); update at least that often with the install command above. A release Gigahost no longer serves gets client_release_unsupported for every command that needs your account, with the release to install and the command that installs it.

Use ghost --help or add --help after any command to see the options supported by the installed version.

Global options

Option	Environment variable	Meaning
--api-url	GHOST_API_URL	The API; the client defaults to https://api.gigahost.cloud
--seed-file	GHOST_SEED_FILE	The seed file that holds the account key
--recovery-seed-file	GHOST_RECOVERY_SEED_FILE	An older account key, for restoring its backups
--json		JSON output
--compact		JSON on one line

Plain HTTP is accepted only when the API URL contains a literal IP address; hostname APIs require HTTPS, and API redirects are not followed.

Output for reading

Without --json or --compact, results are printed for reading:

• Fields are aligned, and lists are one line per item, as tables where they fit the terminal and as short blocks otherwise.
• Values are shown in their units under labels without the unit the API sends them in, such as available $500.00 for available_microusd, memory use in memory-hours, CPU use and uptime as percentages, and network rates in bit/s.
• Timestamps are in UTC without fractions.
• Colors appear only on a terminal and never when NO_COLOR is set.

Caution

Never parse this form or error text in scripts. Use the command’s exit status and the JSON response instead.

JSON output

ghost --json instance list
ghost --compact instance list

The error shape

With either option, a command that fails also prints {"error": {...}} on stdout, whose fields are always there, null where they do not apply:

Field	Meaning
code	The backend’s code, also for a refusal ghost makes itself before it sends anything, where the backend would refuse the same (with status null); recovery_key_mismatch for an account key that does not match the key a hosted backup was encrypted for, which only ghost can tell; no_response when no answer came; or null for a failure of ghost itself, such as a file it cannot read
message	What to do
status	The HTTP status
job_id	The job a conflict names, or the job the backend accepted when the command failed after that, such as a restore whose key offer came too late
request_id	The request’s ID from the error’s body or its x-request-id header, for support
transient	Whether repeating the request with its idempotency key may succeed

The error text still goes to stderr, ending with (request ID) where the answer named one, and the exit status is 1. A job followed with --wait that fails prints its final state instead.

Jobs

ghost job list
ghost job list --instance <INSTANCE_UUID> --state active
ghost job list --kind create_backup --state failed
ghost job get <JOB_UUID>
ghost job watch <JOB_UUID>

Commands that change state create an asynchronous job. Pass --wait to follow its step events on stderr and receive the final result on stdout, or inspect it later.

• --wait prints the job’s ID first, so Ctrl-C stops only the waiting and ghost job watch picks it up again.
• Each event line names its step, and a running step’s line is printed again as its progress grows.

ghost job list

It lists your jobs newest first, including those a provider’s retirement or an empty balance started on your instances and backups.

Option	Takes
--instance	One instance’s jobs and its backups’ jobs
--state	pending, running, succeeded, failed, cancelled, or active for pending and running jobs
--kind	A job kind such as create_instance, create_backup, or rotate_gateway_keys
--limit	1 to 200; a page holds 50 jobs by default
--cursor	The previous page’s next_cursor

For reading, the list shows each job’s ID, kind, state, progress, and creation time, and the error code of a job that failed.

ghost job get

• It shows a job’s steps, its newest 1,000 events with the step each belongs to, and its progress, and the current step’s own.
• A job’s progress is the mean of its steps’, but a step that moves a whole disk, a backup’s upload or a restore’s writing, makes nine tenths of it.
• The upload counts the data it has read and, far lighter, the zeros, so it moves steadily to its end.
• A hosted restore’s wait for your authorization counts as part of its transfer, so its progress does not drop when you authorize it.
• Steps are named by their key; their IDs, which no command takes, are only in --json.
• The job’s result holds, by step, only the fields meant for you, such as a new backup’s size and SHA-256, or whether a restored instance is running and must grow its filesystem to use a larger disk; the host’s own paths and names are left out.
• ghost job get and ghost job watch with an ID that names no job of yours say so, and that ghost job list lists your jobs.

Retries and idempotency

For safely retried automation, supply the same --idempotency-key each time you retry one requested change. ghost makes a new key for every command unless you pass --idempotency-key.

• When a request gets no answer, times out, is rate limited, or fails on the server, ghost prints the --idempotency-key that repeats exactly that change.
• For an instance you named by its name, it also prints the instance’s ID to repeat the change with, since by then the name may stand for another instance.
• A rejection prints none, since the same request would be rejected again.
• A conflict with a job still running on the resource ends with the ghost job watch <JOB_UUID> command that follows it; retry once that job has finished.
• A read that gets no answer at all, because the connection failed, timed out or closed, is sent twice more, after 1 and 2 seconds, with a notice on stderr. ghost never repeats a change by itself.

An idempotency key belongs to one kind of change on one resource: a creation to your account, and other changes to their instance, backup, or ticket. For 30 days, the same key with the same request returns the first answer again, even for an instance deleted since, and with a different request it is refused with idempotency_key_reused.

Error codes

A refused request answers with a stable code and a message that says what to do; a conflict with a job still running on the resource also names it as job_id. Common codes:

Code	Meaning
instance_provisioning	The instance is still being created or reinstalled; wait for job_id.
operation_in_progress, backup_in_progress	Another job is running on the instance; wait for job_id. Without a job_id, the instance changed state during the request: retry it.
instance_stopped	A stopped instance cannot be rebooted or reset; start it instead.
instance_failed	The instance’s creation or last reinstall failed; reinstall or delete it, as the message says.
instance_deleting, instance_deleted	The instance is being or has been deleted.
not_home_instance	Gateway commands apply only to home instances.
idempotency_key_reused	The key was already used for a different request.
invalid_offering_token	The offering ID is not of2_ and 22 base64url characters; the message says whether the prefix, a character, the length, or the last character is wrong. Copy one from ghost catalog offerings.
offering_unavailable	The offering’s terms changed, or none of its hosts takes new instances; list the offerings again.
capacity_unavailable	No host of the offering has room now, or a local backup’s host is full or takes no new instances. The message says what the hosts lack: a free public IPv4 address (and until when a resting one rests), cores, memory, or root storage, or that a host keeps its last address for the largest size that fits it. For a home instance it names what the gateways lack: a free public address at the location, with when one is free again, or a gateway that can be set up or has room.
offering_not_on_host	The upgrade names a size of another host; ghost instance upgrades lists the sizes the instance can take.
not_an_upgrade	The offering is the instance’s own size, or smaller in what the message names.
insufficient_balance	Your available balance does not cover the request; the message names what it needs and what is available.
backup_host_mismatch	The offering cannot place an instance on the host that stores the local backup; find one with --for-backup.
backup_started	The host has begun the backup, so you cannot cancel it any more; wait for job_id and delete the backup then, or ask support, since only the operator can cancel it.
backup_not_available	Only an available backup can be restored or give a new instance, and only an available or lost one deleted; the message says what the backup is doing.
backup_pool_unavailable	The local backup’s host is missing the backup pool that holds it, or checks it since it came back; try again later.
local_backups_unavailable, backup_too_large_for_host, backup_storage_busy	The instance’s host keeps no local backups, or has no room for this one now; the message says what would fit, as under When a local backup does not fit.
account_not_activated	No account is registered for this account key yet; activate it first.
auth_key_retired	An account key migration retired the account key that signed the request; select the new account key.
ticket_closed	Reopen the ticket before replying.
review_revision_conflict	Pass the review’s current revision.

Renter commands

Each command is explained on the page it links to. Provider commands, and ghost account history, deposits, sla-credits, review, approve and ghost catalog reviews, are on Provider commands for now.

Account

Command	What it does
ghost key generate, ghost key inspect	Create the account key and show its public identities
ghost account activation-terms, activate, show, balance	Activate the account and show it
ghost account trial, trial-status	Start a free trial by signing in with GitHub, and read its claim
ghost account auth-keys	List the authentication keys
ghost account ssh-keys add, list, remove	Saved SSH keys
ghost account login	A website login link
ghost account sessions, revoke-session, revoke-sessions	End website sessions
ghost account set-password, remove-password	The website password
ghost account migrate-seed	Migrate to a new account key
ghost account notifications	Notifications

Catalog

Command	What it does
ghost catalog offerings (ghost catalog), offering	Find an offering
ghost catalog locations	Locations
ghost catalog images	Images
ghost catalog provider, network-test	Compare providers

Instances

Command	What it does
ghost instance create	Rent an instance
ghost instance list, get, rename	List and inspect instances
ghost instance power	Power
ghost instance console-log	Console
ghost instance reinstall	Reinstall
ghost instance upgrades, upgrade	Upgrade
ghost instance delete	Delete
ghost instance usage	Usage history
ghost instance ports	Shared IP and ports
ghost instance gateway-location	Gateway location
ghost instance gateway-traffic	Gateway traffic
ghost instance rotate-gateway-keys	Rotate the gateway keys

Backups

Command	What it does
ghost backup create	Make a backup
ghost backup list, get	List and inspect backups
ghost backup cancel	Cancel a backup
ghost backup restore	Restore over the instance
ghost backup delete	Delete a backup

Work inside an instance

ghost x runs a command on an instance through ghostd, its output and exit code passed through without any quoting, and ghost mcp gives an AI agent such as Claude Code tools to run commands and jobs and to read, write and edit files there:

ghost ghostd install web-1
ghost x web-1 -- ls -la /srv
claude mcp add ghost -- ghost mcp

See AI agents on instances.

Jobs and support

Command	What it does
ghost job list, get, watch	Jobs
ghost support create, list, get, reply, state	Support