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.

Variable Promotions (Approval Workflow)

Need to request cross-environment key changes with an explicit review step?

Use promotion requests

Create and review variable promotion requests with ghostable env promote workflows.

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

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.

string

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

string

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

boolean

Skip confirmation prompts and proceed automatically.

boolean

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

boolean

Alias for --sync.

boolean

Alias for --sync.

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.

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.

string

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

string

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

boolean

Skip confirmation prompts and proceed automatically.

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.

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.

string

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

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.

string

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

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.

string

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

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.

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.

In interactive terminals, var push also prompts for an optional Reason for change. That reason is encrypted client-side and attached to the exact version created by the push.

Variable Notes and Comments

Use var context when you want to work on the shared note or comments for a single variable.

ghostable var context

The CLI walks you through environment and variable selection, then lets you:

review the current note and comment thread,
replace the shared note,
add a new comment,
delete one of your own comments,
refresh the context view after a teammate updates it.

Adding a comment uses a normal inline prompt. Editing the note uses a multiline terminal composer so you can keep line breaks without leaving the CLI.

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.

string

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

string

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

string

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

string[]

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

boolean

Preview which variables would be pulled without writing any files.

boolean

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

boolean

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

boolean

Remove local variables that no longer exist on the server.

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.

string

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

string

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

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.

string

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

string

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

string

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

string

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

string[]

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

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. History includes the new variable context workflow as well. Depending on the event, you may see:

note updates,
comment creation or deletion,
variable updates tagged with a reason for change.

The activity rows stay metadata-only. They tell you what happened and who did it without exposing decrypted note or comment bodies in the history table. 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).

string

Environment to inspect. Defaults to an interactive picker.

Workflows

Automation & CI

Reference

Need the shared environment model?

Variable Promotions (Approval Workflow)

Use promotion requests

Listing Environments

Creating Environments

Pushing Variables

Ignoring Variables

Refreshing Local Version State

Syncing Variables

Command comparison

Validating Variables

Pushing a Single Variable

Variable Notes and Comments

Pulling Variables

Pulling a Single Variable

Comparing Environments

What’s Compared

Possible Outcomes

Viewing Change History

Need the shared environment model?

​Variable Promotions (Approval Workflow)

Use promotion requests

​Listing Environments

​Creating Environments

​Pushing Variables

​Ignoring Variables

​Refreshing Local Version State

​Syncing Variables

​Command comparison

​Validating Variables

​Pushing a Single Variable

​Variable Notes and Comments

​Pulling Variables

​Pulling a Single Variable

​Comparing Environments

What’s Compared

Possible Outcomes

​Viewing Change History

Variable Promotions (Approval Workflow)

Listing Environments

Creating Environments

Pushing Variables

Ignoring Variables

Refreshing Local Version State

Syncing Variables

Command comparison

Validating Variables

Pushing a Single Variable

Variable Notes and Comments

Pulling Variables

Pulling a Single Variable

Comparing Environments

Viewing Change History