Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ghostable.dev/llms.txt

Use this file to discover all available pages before exploring further.

Need the shared deploy token model?

Read the Fundamentals page for the shared deploy token model, then use this guide for CLI steps.

​
Why Deploy Tokens?

Deployment tokens let CI/CD runners fetch and decrypt Ghostable secrets without relying on a human-linked device. Each token targets a single environment and carries:
  • GHOSTABLE_CI_TOKEN — authenticates API calls (list, pull, deploy, etc.).
  • GHOSTABLE_DEPLOY_SEED — the private key used to derive environment keys.
Tokens are ideal for GitHub Actions, GitLab, Forge, Vapor, or any automation that should not hold a full CLI session.
Treat both secrets like production credentials. Store them in your CI secret manager and rotate regularly.

​
Creating a Token

Run the CLI wizard from a trusted workstation: 
$ ghostable deploy token create
? Which environment should the deployment token target?  production
? Token name (shown in Ghostable dashboard)  production-ci
What happens next:
  1. You confirm (or override) the environment and name.
  2. The CLI mints a fresh keypair, registers the token, and re-shares the environment key with it.
  3. You receive the API token (GHOSTABLE_CI_TOKEN) plus the private key (GHOSTABLE_DEPLOY_SEED). If you enter a file path when prompted (or pass --out), the seed is written there with mode 600.
Example output: 
Token ID: dpl_tok_019bb7f0b3e4
Environment: production
Token Expires: 2024-09-15 15:32 -0500 (in 30 days)
Token Suffix: …42KD

GHOSTABLE_CI_TOKEN="gtok_1Jb…"
GHOSTABLE_DEPLOY_SEED="b64:ABC123…"

Store this information securely — it cannot be retrieved again.
If you misplace either secret, revoke the token and create a new one. Ghostable never stores the private key in plaintext.

​
Listing Tokens

See which tokens exist for a given environment: 
$ ghostable deploy token list
? Which environment should the deployment token target?  production
The table shows the token name, status (active/revoked), last usage, and creation time. Use this to spot stale runners or confirm rotation.

​
Rotating a Token

Refresh the keypair (for example, before the API token expires) without changing the token ID: 
$ ghostable deploy token rotate
? Which environment should the deployment token target?  production
? Select a deployment token to rotate  production-ci (active · last used 2h ago)
Rotation steps:
  1. The CLI mints a new encryption keypair.
  2. Ghostable replaces the token’s public key.
  3. The environment key is re-shared with the rotated token and your current device.
  4. You receive a new private key; update GHOSTABLE_DEPLOY_SEED in your CI.
If you omit --token, the CLI prompts you to select from active tokens.

​
Revoking a Token

Remove access immediately when a runner is retired or compromised: 
$ ghostable deploy token revoke
? Which environment should the deployment token target?  production
? Select a deployment token to revoke  production-ci (active · last used 2h ago)
Revoking deletes the token server-side and re-shares the environment key with the remaining trusted identities. Once revoked, the token cannot be restored—create a new one if needed.

​
Tips

  • One token per environment: keep scopes tight so you can revoke/rotate without affecting other deployments.
  • Short expirations: the CLI supports limited lifetimes; shorter windows reduce blast radius.
  • Version control: never commit the .txt files produced by --out. Upload them to your secret manager and delete the local copy afterward.
  • If a token can’t decrypt: re-run ghostable deploy token rotate (or create) from a trusted device to re-share the environment key with that token.

​
Command Options Reference

​
deploy token create --env <ENV>
string
Skip the prompt and target a specific environment by slug or ID.
​
deploy token create --name <NAME>
string
Provide a display name ahead of time (defaults to <env>-ci).
​
deploy token create --out <FILE>
string
Write the private key to a file instead of stdout. File is created with 0600 permissions.
​
deploy token list --env <ENV>
string
List tokens for the given environment without prompting.
​
deploy token rotate --env <ENV>
string
Specify the environment that owns the token you’re rotating.
​
deploy token rotate --token <ID>
string
Rotate a particular token ID without going through the picker.
​
deploy token rotate --out <FILE>
string
Save the replacement private key to disk (same behavior as create).
​
deploy token revoke --env <ENV>
string
Select the owning environment non-interactively.
​
deploy token revoke --token <ID>
string
Revoke a specific token ID without the interactive selection step.