Environments | Ghostable CLI 3.x | Ghostable Menu Environments Environment types ----------------- 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. `default, local, dev, test, ci` Not protected unless the environment type explicitly contains prod, production, or live. `production, prod-us, live` Protected because the name contains an explicit production token. `preview, staging, qa, primary, custom names` Protected by the conservative fallback, even when the type is development. Names determine the safe fallback A custom type such as `development` does not make a neutral environment name unprotected. Use an explicit local-development token in the environment name when that is the intended trust level. List environments Copy ``` $ ghostable env list $ ghostable env list --json ``` Create and seed --------------- Create environments Copy ``` $ 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. Push and sync ------------- `env push` creates or updates keys present in a file without removing other stored keys: Push values Copy ``` $ 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: Synchronize an environment Copy ``` $ ghostable env sync --env staging --file .env.staging --reason "Remove retired integration" ``` Sync is destructive Diff first. A truncated or incorrect input file can turn an intended update into many signed deletions. Pull values ----------- 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. Materialize values Copy ``` $ 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. Supported dotenv syntax ----------------------- 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`. `Comments and layout` Merge operations preserve blank lines, comments, unrelated keys, and an existing export prefix. `Duplicate keys` The last occurrence wins when reading. Updating that key removes its earlier duplicate entries. `Key normalization` Imported keys are trimmed, uppercased, and normalized to letters, numbers, and underscores. `Interpolation` Values such as ${APP\_URL} remain literal; Ghostable does not expand shell or dotenv references. `Multiline values` Quoted values must remain on one physical line. Use escaped newline sequences or another encoding for multiline data. 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. Run without a file ------------------ Inject decrypted values directly into a child process to reduce plaintext files on disk: Process injection Copy ``` $ 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. Compare and audit ----------------- Diff and history Copy ``` $ 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. Rename and delete ----------------- Environment lifecycle Copy ``` $ ghostable env rename --from preview-42 --to preview-43 --reason "Match deployment environment" $ ghostable env delete --env preview-43 ``` Both operations modify repository-backed state. Review and commit the resulting `.ghostable/` changes immediately. On this page [ ![Ghostable](https://ghostable.dev/images/logo-dark.svg) ![Ghostable](https://ghostable.dev/images/logo-light.svg) ](https://ghostable.dev) CLI 3.x [ CLI 3.x ](https://ghostable.dev/docs/3.x) [ Desktop ](https://ghostable.dev/docs/desktop) CLI 3.x introduction Documentation local first no login encrypted repository plaintext hosted service Installation Documentation brew homebrew npm npx linux windows PATH version update Start a new project Getting Started setup seed dotenv owner initialize Adopt an existing project Getting Started existing env import authoritative source adopt Onboard a team member Getting Started join request approve roles offboarding pull request Repository and storage Core Concepts .ghostable git conflict merge worktree private identity metadata Environments Core Concepts protected production preview staging push sync pull replace run mask-output Variables and promotions Core Concepts var promote copy context annotation key Access and devices Core Concepts identity reader writer grantor owner revoke rotate leave delete Daily development workflow Workflows pull diff validate review clean daily Review and secret scanning Workflows scan sarif github suppress secrets drift Hygiene and rotation Workflows rotation stale unused suppression environment key Automation credentials Automation & CI GHOSTABLE\_CI\_TOKEN ci deploy credential powershell revoke replace Continuous integration Automation & CI GitHub Actions fork pull request JSON stdout stderr exit codes mask-output Deployments Automation & CI Forge Vapor Cloud provider CLI dry-run preserve remote keys temporary files Validation Reference schema required nullable regex min max different\_from Command reference Reference --help --json NO\_COLOR flags aliases exit code automation Configuration Reference ghostable.yaml activity mode auditEnvironments scan ignores deployTarget dotenv syntax Security Reference cryptography XChaCha20 Poly1305 HKDF user presence threat model Backups & Offline Reference recovery offline restore clone key identity Agent integration Reference AGENTS.md capabilities allowlist coding agent Troubleshooting Reference no project found revoked identity stale policy user presence invalid CI token provider CLI git conflict diagnostics Ghostable Desktop overview Desktop Installation Desktop Projects and setup Desktop Interface tour Desktop Environments and variables Desktop Local environment files Desktop Validation and review Desktop Activity Desktop Access and automation Desktop Project settings Desktop Application settings Desktop Licensing and updates Desktop Security and storage Desktop Troubleshooting Desktop No results found