Environments

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

Merge remote-only keys before pushing so you don’t clobber teammates’ latest values. Local changes still win on conflicts.

--replace

boolean

Replace all existing variables on the server with your local .env contents.

--prune-server

boolean

Delete remote variables that no longer exist in your local .env file.

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.

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.

Command comparison

Command	Behavior	Remote effect	Prunes missing keys?	When to use
`ghostable env push`	Upload only the keys in your current file	Updates/creates provided keys; untouched keys remain	No	Routine updates when you only changed a handful of values
`ghostable env push --sync`	Pull remote-only keys before pushing	Same as `env push`, but merges remote keys first to avoid accidental overwrites	No	Collaborative edits where teammates may have added keys in Ghostable
`ghostable env push --replace`	Force remote to match your file	Rewrites all keys with your local values	No	Emergency resets when you know your local file is authoritative
`ghostable env push --prune-server`	Remove keys absent locally	Deletes any remote key not found in your file	Yes (only for missing keys)	Cleaning up deprecated variables without a full sync
`ghostable env sync`	Treat local file as source of truth	Remote variables replaced wholesale with local copy	Yes	Rebuild environments from scratch or enforce a golden `.env`

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 deep-dive 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.

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.

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)	[email protected]	update	`APP_URL`	v12	URL changed to prod host
1 day ago (2024-06-04 09:02)	[email protected]	comment	`DEBUG`	v11	Flag commented out
3 days ago (2024-06-02 18:45)	[email protected]	create	`API_KEY`	v1	New key provisioned

Returned 3 change(s).

--env

string

Environment to inspect.
Defaults to an interactive picker.

Getting Started

The Basics

Digging Deeper

Listing Environments

Creating Environments

Pushing Variables

Ignoring Variables

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

Getting Started

The Basics

Digging Deeper

​Listing Environments

​Creating Environments

​Pushing Variables

​Ignoring Variables

​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

Syncing Variables

Command comparison

Validating Variables

Pushing a Single Variable

Pulling Variables

Pulling a Single Variable

Comparing Environments

Viewing Change History