Environments

Need the shared environment model?

Read the Fundamentals page for the shared object model, then use this guide for CLI commands.

Each project can have as many environments as you need. While production and staging are common defaults, you’re free to create environments for feature branches, client-specific setups, QA, or any other workflow you use. Environments define how variables are organized, accessed, and shared within your team. You can safely push, pull, or deploy environment data using the Ghostable CLI, and every operation is scoped to a specific environment and auditable.

Think of environments as named contexts for your configuration — isolated, auditable, and built for secure collaboration.

Listing Environments

The env list command displays all environments associated with the current project as defined in your .ghostable/ghostable.yaml manifest.

ghostable env list

You’ll see each environment’s ID, name, type, and base (if applicable) in a structured table.

Note: You must be logged in and have an initialized project (ghostable init) before using this command.

Creating Environments

To create a new environment, run the env create command:

ghostable env create

You’ll be prompted to:

Select an environment type (e.g., Production, Staging)
If --name isn’t provided, choose a suggested name or enter a custom slug-formatted name

--name

string

Environment name (slug)

Pushing Variables

To upload your local .env file to Ghostable, use the push command:

ghostable env push

This command securely uploads your environment variables to Ghostable for the currently linked project and organization. If no environment is specified, you’ll be prompted to select one interactively.

Ghostable only pushes keys that exist in your local .env file. It will not remove remote keys unless explicitly told to using —prune-server.

--env

string

Specify which environment to push (e.g. production, staging). If omitted, Ghostable will prompt you to choose.

--file

string

Path to the .env file to read from.
Defaults to .env.<env> or .env if unspecified.

--assume-yes

boolean

Skip confirmation prompts and proceed automatically.

--sync

boolean

Prune remote variables that are not present in your local .env file. This is equivalent to --replace, --prune-server, and env sync.

--replace

boolean

Alias for --sync.

--prune-server

boolean

Alias for --sync.

--conflict-mode

string

Conflict handling mode for push operations:

strict (default): block the push when local and server versions drift.
warn: detect stale keys. In interactive terminals, Ghostable prompts you to pull latest values, continue overwrite, or cancel.

--force-overwrite

boolean

Bypass optimistic conflict checks and force overwrite remote values.

In interactive warn mode, choosing Pull latest and cancel push runs ghostable env pull immediately, updates your local .env target file, and cancels the push so you can review changes before retrying. Use --assume-yes to skip this prompt.

Ignoring Variables

Some secrets (deployment tokens, platform-specific values, etc.) should never leave your machine. List them under the ignore key for an environment inside .ghostable/ghostable.yaml and the CLI will skip them during env push, env sync, var push, and var pull.

environments:
    production:
        type: production
        ignore:
            - GHOSTABLE_CI_TOKEN
            - STRIPE_WEBHOOK_SECRET

Ignored keys remain untouched remotely and locally. They also appear in summaries when you pass --show-ignored to commands like env pull or env diff, so you know they were intentionally skipped.

Refreshing Local Version State

Ghostable tracks local key version baselines in .ghostable/state/... so strict conflict mode can detect stale writes.

ghostable env state refresh --env production

You can also run ghostable env state with no subcommand for guided refresh. Run this when:

You want strict conflict checks before pushing.
Teammates updated the same environment recently.
CI needs a fresh version baseline before env push --conflict-mode strict.

ghostable env pull refreshes this version baseline automatically after a successful pull.

env state refresh updates local version baselines only. It does not pull new secret values into your local .env file. Run ghostable env pull --env <env> if you need value sync before pushing.

Syncing Variables

The env sync command provides a one-way synchronization between your local .env file and the remote environment in Ghostable.

ghostable env sync

It treats your local file as the source of truth—remote variables are replaced wholesale and keys that no longer exist locally are pruned.

--env

string

Specify which environment to sync (e.g. production, staging). If omitted, Ghostable will prompt you to select one.

--file

string

Path to the local .env file to read from.
Defaults to .env.<env> or .env if unspecified.

--assume-yes

boolean

Skip confirmation prompts and proceed automatically.

--conflict-mode

string

Conflict handling mode for sync operations:

strict (default): block sync when local and server versions drift.
warn: detect stale keys and continue after warning or guided confirmation.

--force-overwrite

boolean

Force overwrite server values even when strict conflict checks would block.

Command comparison

Command	Behavior	Remote effect	Prunes missing keys?	When to use
`ghostable env push`	Upload only keys in your current file	Updates/creates provided keys; untouched keys remain	No	Routine updates when you changed a subset of values
`ghostable env push --sync`	Push and prune remote extras	Deletes remote keys not present locally while pushing submitted keys	Yes	Enforce local `.env` as source of truth for that environment
`ghostable env push --replace`	Alias for `--sync`	Same as `env push --sync`	Yes	Teams that prefer explicit “replace” wording
`ghostable env push --prune-server`	Alias for `--sync`	Same as `env push --sync`	Yes	Teams that prefer explicit prune wording
`ghostable env sync`	Shortcut to push with prune behavior	Same as `env push --sync`	Yes	Faster command for one-way synchronization workflows

Validating Variables

Run schema validation before pushing or deploying to catch bad values early. The command pulls schema.yaml plus any per-environment overrides and validates your local .env:

ghostable env validate --env production

Output lists failing keys (if any) and exits non-zero so you can wire it into CI. See the Validation rules guide for rule syntax.

--env

string

Environment whose .env should be validated. If omitted, the CLI prompts you to choose.

--file

string

Optional path to a non-standard .env file. Defaults to .env.<env> or .env.

Pushing a Single Variable

var push encrypts one environment variable from your local .env file and uploads it to Ghostable. It reads project + environment info from .ghostable/ghostable.yaml, respects your ignore rules, and uses your local CLI keys to encrypt before upload.

ghostable var push

This command only sends the one variable you select. It won’t touch other keys locally or remotely.

--env

string

Environment to push to (e.g. production, staging). If omitted, you’ll be prompted to choose from your manifest.

--key

string

The environment variable name to push (e.g. APP_URL). If omitted, the CLI lists variables from the resolved .env and prompts you to choose.

--file

string

Path to the .env file to read from.
Defaults to .env.<env> when --env is provided, otherwise .env.

--conflict-mode

string

Conflict handling mode for single-variable pushes:

strict (default): block the push when local and server versions drift.
warn: detect stale key versions. In interactive terminals, Ghostable prompts you to pull latest values, continue overwrite, or cancel.

--force-overwrite

boolean

Force overwrite the selected key even if local and server versions differ.

In interactive warn mode, Pull latest and cancel push runs ghostable env pull for the environment, updates the local .env target file, and cancels the single-key push.

Pulling Variables

To fetch a remote environment and write it to your local .env file, use the pull command:

ghostable env pull

This command downloads the latest variables from Ghostable for the selected environment and writes them to your local .env file.

If your device is newly linked and key access is not yet shared, pull/diff commands return an explicit pending key re-share state (ENV_KEY_RESHARE_REQUIRED) with guidance instead of a generic failure.

Your local .env file will be overwritten unless you use --dry-run. By default, Ghostable automatically creates a timestamped backup of your existing .env file before writing.You can disable this behavior with --no-backup.

--env

string

Specify which environment to pull (e.g. production, staging). If omitted, Ghostable will prompt you to select one.

--file

string

Path to the .env file where variables will be written.
Defaults to .env.<env> or .env if unspecified.

--format

string

Output format for the generated file. Accepts alphabetical, grouped, or grouped:comments. If omitted, the CLI prompts you to choose interactively.

--only

string[]

Pull only specific variable keys. Can be repeated, e.g. --only APP_KEY --only DB_PASSWORD.

--dry-run

boolean

Preview which variables would be pulled without writing any files.

--show-ignored

boolean

Show variables that were skipped (ignored) during pull due to local configuration or filters.

--replace

boolean

Replace the entire local .env file instead of merging values.

--prune-local

boolean

Remove local variables that no longer exist on the server.

--no-backup

boolean

Skip automatic backup creation.

Pulling a Single Variable

var pull fetches one environment variable from Ghostable, decrypts it locally using your CLI keys, and upserts it into your target .env file (creates the file if missing, replaces the line if it exists, or appends a new line). If the variable’s metadata marks it as commented, the line is written as a comment.

ghostable var pull

This command only touches the one variable you request. It won’t prune or rewrite other keys.

--env

string

Environment to pull from (e.g. production, staging). If omitted, you’ll be prompted to choose from your manifest.

--key

string

The environment variable name to pull (e.g. APP_KEY). If omitted, you’ll be shown a selectable list from the remote environment.

--file

string

Destination file to update.
Defaults to .env.<env> when --env is provided, otherwise .env.

Comparing Environments

The env diff command helps you see what’s changed between your local .env file and the version stored in Ghostable.

ghostable env diff

How It Works

The command pulls the latest encrypted environment bundle from Ghostable for the selected project and environment.
It then decrypts that bundle locally using your master seed (stored in the OS keychain).
It reads your local .env file, parses each variable, and compares the two sets of values.

Because Ghostable is zero-knowledge, the diff is performed entirely on your machine — no plaintext values are ever sent to Ghostable’s servers.

What’s Compared

For each environment variable, Ghostable compares:

Field	Description
Name	The variable key (for example, `APP_KEY`, `DB_HOST`).
Value	The decrypted plaintext value from Ghostable compared against the value in your local `.env`.
Commented State	Indicates whether the variable is commented or active, based on Ghostable’s stored metadata.

Possible Outcomes

The diff output highlights three types of changes:

Symbol	Meaning	Example Output
`+`	Added locally – exists in your `.env` but not in Ghostable	`+ NEW_FEATURE_FLAG=true`
`~`	Updated – exists in both but values differ	`~ APP_URL: https://old -> https://new`
`-`	Removed locally – exists in Ghostable but not in your `.env`	`- LEGACY_SETTING=on`

If there are no differences, you’ll see: No differences detected.

--env

string

Specify which environment to compare (e.g. production, staging) and skip the interactive picker.

--file

string

Path to the local .env file to diff against (default: .env.<env> or .env).
Alias for --local.

--local

string

Explicit local .env path. Same as --file; provided for compatibility with older scripts.

--token

string

API token to use for the remote pull. If omitted, the CLI uses your logged-in session or GHOSTABLE_TOKEN.

--only

string[]

Diff only specific variable keys. Repeatable, e.g. --only APP_KEY --only DB_PASSWORD.

--show-ignored

boolean

Show variables that were skipped (ignored) during comparison due to local configuration or filters.

Viewing Change History

Audit every change to an environment with the env history command (legacy alias: env audit). It summarizes recent activity and prints a table of individual operations.

ghostable env history --env production

You’ll see who changed which key, when it happened, whether the key was commented, and the version number associated with the change. Handy for debugging regressions or reviewing peer updates. Example output:

When	Actor	Operation	Key	Version	Notes
2 hours ago (2024-06-05 10:17)	dev@example.com	update	`APP_URL`	v12	URL changed to prod host
1 day ago (2024-06-04 09:02)	dev@example.com	comment	`DEBUG`	v11	Flag commented out
3 days ago (2024-06-02 18:45)	ops@example.com	create	`API_KEY`	v1	New key provisioned

Returned 3 change(s).

--env

string

Environment to inspect. Defaults to an interactive picker.

Workflows

Automation & CI

Reference

Need the shared environment model?

Listing Environments

Creating Environments

Pushing Variables

Ignoring Variables

Refreshing Local Version State

Syncing Variables

Command comparison

Validating Variables

Pushing a Single Variable

Pulling Variables

Pulling a Single Variable

Comparing Environments

What’s Compared

Possible Outcomes

Viewing Change History

Workflows

Automation & CI

Reference

Need the shared environment model?

​Listing Environments

​Creating Environments

​Pushing Variables

​Ignoring Variables

​Refreshing Local Version State

​Syncing Variables

​Command comparison

​Validating Variables

​Pushing a Single Variable

​Pulling Variables

​Pulling a Single Variable

​Comparing Environments

What’s Compared

Possible Outcomes

​Viewing Change History

Listing Environments

Creating Environments

Pushing Variables

Ignoring Variables

Refreshing Local Version State

Syncing Variables

Command comparison

Validating Variables

Pushing a Single Variable

Pulling Variables

Pulling a Single Variable

Comparing Environments

Viewing Change History