> ## 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.

# Deploy Tokens

> Automate deployments securely with short-lived Ghostable deployment tokens.

<Card title="Need the shared deploy token model?" icon="circle-info" href="/fundamentals/v2/core-objects/deploy-tokens">
  Read the Fundamentals page for the shared deploy token model, then use this guide for CLI steps.
</Card>

## 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.

<Warning>
  Treat both secrets like production credentials. Store them in your CI secret manager and rotate
  regularly.
</Warning>

***

## Creating a Token

Run the CLI wizard from a trusted workstation:

```bash theme={null}
$ 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.
```

<Info>
  If you misplace either secret, revoke the token and create a new one. Ghostable never stores the
  private key in plaintext.
</Info>

***

## Listing Tokens

See which tokens exist for a given environment:

```bash theme={null}
$ 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:

```bash theme={null}
$ 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:

```bash theme={null}
$ 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

<ParamField path="deploy token create --env <ENV>" type="string">
  Skip the prompt and target a specific environment by slug or ID.
</ParamField>

<ParamField path="deploy token create --name <NAME>" type="string">
  Provide a display name ahead of time (defaults to `<env>-ci`).
</ParamField>

<ParamField path="deploy token create --out <FILE>" type="string">
  Write the private key to a file instead of stdout. File is created with `0600` permissions.
</ParamField>

<ParamField path="deploy token list --env <ENV>" type="string">
  List tokens for the given environment without prompting.
</ParamField>

<ParamField path="deploy token rotate --env <ENV>" type="string">
  Specify the environment that owns the token you’re rotating.
</ParamField>

<ParamField path="deploy token rotate --token <ID>" type="string">
  Rotate a particular token ID without going through the picker.
</ParamField>

<ParamField path="deploy token rotate --out <FILE>" type="string">
  Save the replacement private key to disk (same behavior as create).
</ParamField>

<ParamField path="deploy token revoke --env <ENV>" type="string">
  Select the owning environment non-interactively.
</ParamField>

<ParamField path="deploy token revoke --token <ID>" type="string">
  Revoke a specific token ID without the interactive selection step.
</ParamField>