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 with --json, so the same commands serve interactive use and automation.

Installing ghost

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

One command installs ghost without root, as ~/.local/bin/ghost. ghost --version prints the installed release. The same command updates it.

• 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 accepts a release only when 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 as root, it installs for every user under /usr/local. GIGAHOST_INSTALL_PREFIX sets another prefix.
• GIGAHOST_INSTALL_VERSION installs one release by name instead of the current one, for example to go back to an earlier release: curl -fsSL https://api.gigahost.cloud/install/ghost.sh | GIGAHOST_INSTALL_VERSION=20261010T120000Z-0123456789ab sh. The script checks that release’s own signed manifest the same way and refuses it unless it names exactly that release.

Keeping 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-…), so updating with the install command above at least that often keeps ghost supported. 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.

ghost --help, or --help after any command, shows the options the installed version supports.

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, such as the account.seed the website’s Create an account page downloads
--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 need 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 not when NO_COLOR is set.

Caution

This form and the error text can change, so scripts are better served by the command’s exit status and the JSON response.

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	Gigahost’s code, also for a refusal ghost makes itself before it sends anything, where Gigahost 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 happened, and what to do when there is something to do
status	The HTTP status
job_id	The job a conflict names, or the job Gigahost 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. --wait follows its step events on stderr and gives the final result on stdout. Without it, the job can be inspected 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 needs to 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, the same --idempotency-key on each retry of one requested change repeats it once, within 30 days (see below). ghost makes a new key for every command unless --idempotency-key is given.

• When a request gets no answer, times out, is rate limited, or fails on the server side, 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. A retry works 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 does not repeat 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. With a different request, Gigahost answers idempotency_key_reused.

Error codes

A request Gigahost does not accept gets a stable code and a message that says what happened and, where something can be done, 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, reinstalled or redeployed; you can try again once the job in job_id has ended.
operation_in_progress, backup_in_progress	Another job is running on the instance; you can try again once the job in job_id has ended. Without a job_id, the instance changed state during the request, and you can retry it.
instance_stopped	A stopped instance cannot be rebooted or reset; you can start it instead.
instance_failed	The instance’s creation or last reinstall failed; you can 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.
instance_is_a_container, instance_is_a_vm	A container instance is redeployed, not reinstalled, and a VM the other way round.
redeploy_unavailable	The instance’s host cannot redeploy container instances yet; you can try again later.
access_reset_unavailable	The instance’s host cannot reset SSH access yet; you can try again later.
rescue_unavailable	The instance’s host cannot boot a rescue yet, or no rescue system is published yet; you can try again later.
instance_in_rescue	The instance is in rescue: end the rescue first, or it is in one already.
instance_not_in_rescue	The instance is in no rescue to end.
stock_image_unsuitable	The stock image needs more memory than the instance has, or CPUs its host lacks; the message says which.
host_lacks_room_to_redeploy	The instance’s host has no room now for the snapshot a redeploy takes; you can try again later.
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. You can copy one from ghost catalog offerings.
offering_unavailable	The offering’s terms changed, or none of its hosts takes new instances; you can 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; you can find one with --for-backup.
backup_started	The host has begun the backup, so you can no longer cancel it. You can 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. The request works once you have activated the account.
auth_key_retired	An account key migration retired the account key that signed the request; you can select the new account key.
ticket_closed	A closed ticket takes no reply; you can reopen it with ghost support state <TICKET_UUID> open and then reply.
review_revision_conflict	To change a review, give its current revision as --expected-revision.

Renter commands

Each command is explained on the page it links to.

Account

Command	What it does
ghost key generate, ghost key inspect	Create the account key and show its public identities
ghost key import	Use an account key made on the website or another machine
ghost account activation-terms, activate, show, balance	Activate the account and show it; balance adds the monthly spending
ghost account signup --github, github-status	Sign up with GitHub, and read its claim
ghost account link-github, unlink-github	Link a GitHub account to the account, or unlink it
ghost account protection set, default	The protected balance new actions leave for your running instances
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
ghost account history	Your charges and receipts
ghost account deposits	Your deposits
ghost account sla-credits	SLA credits
ghost account review	Review a provider
ghost account approve	Approve a hosted backup’s restore

Catalog

Command	What it does
ghost catalog offerings (ghost catalog), offering	Find an offering
ghost catalog locations	Locations
ghost catalog images	Images
ghost catalog container-images	Stock images
ghost catalog provider, network-test	Compare providers
ghost catalog reviews	A provider’s reviews

Instances

Command	What it does
ghost instance create	Rent an instance, or a container instance
ghost instance list, get, rename	List, filter, sort and inspect instances
ghost instance tag, tags	Tag instances, and list your tags; redundant tags
ghost instance power	Power
ghost instance console-log	Console
ghost instance console	The live console over SSH
ghost instance logs	A container’s logs
ghost instance reinstall	Reinstall
ghost instance redeploy	Redeploy a container
ghost instance reset-access	Reset SSH access
ghost instance rescue	Rescue boot
ghost instance upgrades, upgrade	Upgrade
ghost instance delete	Delete
ghost instance usage	Usage history, with the instance’s monthly spending
ghost instance ports	Shared IP and ports
ghost instance gateway	Change the gateway of a home instance
ghost instance gateway-location	Gateway location, the same as 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, filter, sort and inspect backups
ghost backup cancel	Cancel a backup
ghost backup restore	Restore over the instance
ghost backup delete	Delete a backup
ghost backup schedule show, set, clear	Schedule backups and what they keep

Working 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

Provider commands

Each command is explained on the provider page it links to.

Hosts

Command	What it does
ghost account get-host-enrollment-token	Create an enrollment token
ghost provider hosts, ghost provider host <HOST_UUID>	List your hosts and show one
ghost provider host resume, pause	Control rental admission
ghost provider host private, public, ghost provider private-renters list, add, remove	Private hosts
ghost provider host metrics, instance-usage	Watch a host
ghost provider incidents, ghost provider incident get, acknowledge, resolve	Review incidents
ghost provider uptime, ghost provider outages, ghost provider outage <OUTAGE_UUID>	Uptime and outages
ghost provider host retire, ghost provider retire-instance	Retire a host with notice
ghost provider host emergency	A host that is lost for good
ghost provider host delete	Retire an empty host

Prices

Command	What it does
ghost provider pricing, set-pricing	Publish with ghost

Public addresses of a cloud host

Command	What it does
ghost provider ip-pool create, ghost provider ip add, ghost provider ip-pools	Register public addresses
ghost provider ip remove	Remove an address
ghost provider ip-pool delete	Delete a pool
ghost provider ip-pool hand-over	Hand a pool to a new host identity
ghost provider ip check, ghost provider host check-path	Address and host checks

Payouts

Command	What it does
ghost provider set-payout-address	The payout address
ghost provider balance	The balance
ghost provider payout, payouts	Request and follow payouts