Environments

Every environment has a name and a type. Interactive creation offers local, development, preview, staging, production, or a custom type. Types document intent and participate in protected-environment detection.

Protected-environment detection is intentionally conservative. A name or type containing the token prod, production, or live is protected. Otherwise, only environment names containing default, local, dev, development, test, testing, or ci are treated as local-development environments. Every other name is protected by default.

$ ghostable env list
$ ghostable env list --json
 

$ ghostable env create preview --type preview
$ ghostable env create staging --type staging --from-env default --seed keys-only
$ ghostable env create production --type production --from-env staging --seed non-sensitive
 

Seed modes are keys-only, non-sensitive, and all. Keys-only establishes layout without copying values. Non-sensitive copies values that do not appear secret. All copies every value and should receive deliberate review.

Use --from-file instead of --from-env when a local env file should provide the initial key layout.

env push creates or updates keys present in a file without removing other stored keys:

$ ghostable env push --env staging --file .env.staging --reason "Configure payment sandbox"
 

env sync also deletes stored keys that are absent from the local file:

$ ghostable env sync --env staging --file .env.staging --reason "Remove retired integration"
 

Pull merges into an existing file by default and creates a timestamped backup before writing. Use --replace for an exact environment snapshot, --only for selected keys, and --dry-run to inspect the operation without writing.

$ ghostable env pull --env default --file .env
$ ghostable env pull --env staging --file .env.staging --replace
$ ghostable env pull --env production --file .env.production --only APP_KEY --only DATABASE_URL
 

--show-values prints plaintext in command output. Avoid it in shared terminals, logs, CI, and agent sessions.

Ghostable uses a line-oriented dotenv parser. It supports unquoted, single-quoted, and same-line double-quoted values; blank lines and comments; optional export prefixes; inline comments introduced by a space followed by #; and disabled entries written as # KEY=value.

Replacing a file renders a normalized snapshot and does not preserve its original comments or layout. Use merge behavior when those details matter, and inspect env diff before writing a file with unfamiliar syntax.

Inject decrypted values directly into a child process to reduce plaintext files on disk:

$ ghostable env run --env default -- php artisan test
$ ghostable env run --env staging --mask-output -- npm run smoke-test
$ ghostable env shell --env default
 

The child inherits the current process environment by default. Pass --no-inherit to use only Ghostable values plus a minimal system environment, and --strict to validate injected values and fail when requested keys are missing.

--mask-output replaces exact injected values found in child stdout and stderr. It is best-effort log masking, not data-loss prevention: encoded, transformed, split, or file-written values are outside its protection.

$ ghostable env diff --env default --file .env
$ ghostable env diff --from staging --to production
$ ghostable env history --env production --limit 25
$ ghostable env history --env production --key APP_KEY
 

Diff output is redacted unless --show-values is explicitly requested. History records signed actions, environments, keys, devices, and timestamps.