Skip to main content
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:init command: 
ghostable env:init
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
Perform a two-way sync instead of a one-way push — remote changes will be merged with local values.
​
--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.

​
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 pushes your local variables, replacing all existing remote keys and pruning any that no longer exist locally.
​
--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.
​
--assume-yes
boolean
Skip confirmation prompts and proceed automatically.

​
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.
​
--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.
​
--backup
boolean
Create a timestamped backup of your existing .env file before writing changes.
​
--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:
FieldDescription
NameThe variable key (for example, APP_KEY, DB_HOST).
ValueThe decrypted plaintext value from Ghostable compared against the value in your local .env.
Commented StateIndicates whether the variable is commented or active, based on Ghostable’s stored metadata.

Possible Outcomes

The diff output highlights three types of changes:
SymbolMeaningExample 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 pull (e.g. production, staging). Skips the interactive environment selection prompt.
​
--file
string
Path where the .env file will be written.
Defaults to .env.<env> or .env if unspecified.
​
--only
string[]
Diff only specific variable keys.
Can be repeated, 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.