Core Concepts

Variables & Promotions

Change individual values without exposing them in shell history, promote configuration deliberately, and attach the right kind of context to each key.

Write one variable

In an interactive terminal, var push can prompt securely for a value. In scripts or non-interactive sessions, Ghostable requires --file so the value does not appear in shell history.

Update one variable

$ ghostable var push --env staging --key STRIPE_SECRET_KEY --file .env.staging --reason "Rotate sandbox credential"

The file is parsed locally and only the selected key is encrypted and written.

Read one variable

Write a selected variable to an env file without printing it:

Pull one key

$ ghostable var pull --env default --key APP_KEY --file .env

Passing --show-values prints the plaintext value to stdout. Production-like environments require user-presence confirmation before either path can expose the value.

Promote between environments

Promotion is explicit about source, destination, key, mode, and reason:

Promote configuration

$ ghostable var promote --from staging --to production --key FEATURE_API_URL --reason "Release new API endpoint"
$ ghostable var promote --from staging --to production --key STRIPE_SECRET_KEY --mode key-only --reason "Reserve production key layout"

The default value mode copies the value and variable flags. key-only adds the key to the destination layout without copying a secret across environment boundaries.

Delete and history

Variable lifecycle

$ ghostable var history --env production --key LEGACY_API_TOKEN
$ ghostable var delete --env production --key LEGACY_API_TOKEN --reason "Integration retired"

Deletion is signed and reviewable. Use --assume-yes only in a script that has already confirmed its target.

Encrypted context

Variable context is an encrypted note for information that should travel with a key but should not be visible as repository metadata.

Encrypted note

$ ghostable var context --env production --key STRIPE_SECRET_KEY --note "Stored in the platform security vault; contact the payments owner for rotation."

Annotations and status

Annotations are signed, plaintext, typed metadata. Supported values are string, number, and boolean:

Key annotations

$ ghostable var annotation set --env production --key APP_KEY --name owner --string platform
$ ghostable var annotation set --env production --key APP_KEY --name rotation_days --number 90
$ ghostable var annotation set --env production --key APP_KEY --name deploy.managed --bool true
$ ghostable var annotation list --env production --key APP_KEY

Annotations must never contain secrets. Advanced status commands var enable, var disable, and var status control whether a stored key is emitted as active or commented in generated env files.