Available Commands
The SecretStash Node module provides a CLI for securely managing environment variables, device keys, envelopes, and applications.
Introduction
The SecretStash Node CLI lets you securely manage environment variables across multiple applications. It syncs your application's .env with SecretStash using zero-knowledge encryption.
All commands use the secret-stash binary. If installed globally, run commands directly. If installed as a project dependency, prefix with npx:
- Global:
secret-stash <command> - Project dependency:
npx secret-stash <command>
The examples below use the global form.
Global Options
The following option is available on all commands:
-a, --application <id>— Override the Application ID (takes precedence overSECRET_STASH_APPLICATION_ID).
Managing Variables
Listing Variables
View a summary of the variables stored in SecretStash for a given environment. Values are displayed in masked form.
Options
| Flag | Description |
|---|---|
-e, --environment <slug> | (Required) The environment slug (e.g., production). |
Pulling Variables
Retrieve variables from SecretStash, decrypt them locally using your device key, and merge them into your local .env file.
Options
| Flag | Description | Default |
|---|---|---|
-e, --environment <slug> | (Required) The environment slug. | — |
-f, --file <path> | Path to the .env file to update. | .env |
Pushing Variables
Read your local .env file, encrypt the values, and send them to SecretStash.
Options
| Flag | Description | Default |
|---|---|---|
-e, --environment <slug> | (Required) The environment slug. | — |
-f, --file <path> | Path to the .env file to read. | .env |
Push is not available for Testing environments. If the target environment has the testing type, the push command will be blocked with an error. Testing environments are read-only via the CLI and can only be managed through the SecretStash web application.
Notes:
- Variables starting with
SECRET_STASH_are always ignored. APP_KEYandAPP_ENVare ignored by default.
Managing Environments
List Environments
Show all environments for the current application:
Each entry displays the environment name, slug, and type.
Create an Environment
Create a new environment in SecretStash:
Options
| Flag | Description |
|---|---|
-n, --name <name> | (Required) The environment name (e.g., Staging). |
-s, --slug <slug> | (Required) A URL-friendly slug (e.g., staging). This should match the APP_ENV value. |
-t, --type <type> | (Required) The environment type: development, staging, production, or testing. |
The testing type is intended for CI/CD pipelines. Environments created with this type are read-only via the CLI — variables can only be managed through the SecretStash web application.
Managing Device Keys
SecretStash uses client-side encryption with RSA-4096 key pairs. Device keys are stored locally in ~/.secret-stash by default. You can override this directory by setting the SECRET_STASH_KEY_DIR environment variable.
Initialize Device Key
Generate and register a new RSA-4096 key pair for this device:
Options
| Flag | Description |
|---|---|
-l, --label <label> | A custom label for this device (e.g., "Work MacBook"). Defaults to the hostname. |
-f, --force | Force regeneration of existing keys. |
-t, --temporary | Create a short-lived key for CI/CD pipelines. See CI/CD Integration. |
--ttl <minutes> | TTL in minutes for temporary keys. Only applies when --temporary is also passed. |
Check Key Status
View the status of your local device key and its server registration:
Sync Device Key
Re-sync your local device metadata from the SecretStash server:
Generate Recovery Key
Generate a recovery share file for your device key:
Options
| Flag | Description |
|---|---|
-o, --output-dir <dir> | Output directory for the recovery share file. |
-f, --force | Replace an existing recovery key. |
Managing Envelopes
Envelopes are central to SecretStash's zero-knowledge encryption model. Each environment has a Data Encryption Key (DEK) used to encrypt variable values. The DEK is wrapped (encrypted) with each registered device's RSA public key, creating an "envelope." Only the intended device, using its local private key, can unwrap the envelope and access the DEK.
Rewrap Envelope
Migrate access from an old device key to your current device key. Use this when you have replaced a device key but still have access to the old private key.
Options
| Flag | Description |
|---|---|
-e, --environment <slug> | (Required) The environment slug. |
--old-key-path <path> | (Required) Path to the old private key PEM file. |
--old-device-key-id <id> | (Required) The ID of the old device key. |
Reset Envelope
Generate a brand-new DEK and create new envelopes for all registered device keys.
This is a destructive action. Once reset, all team members must pull the latest variables and re-push them to ensure they are encrypted with the new key. Any variables not re-pushed will be inaccessible.
Options
| Flag | Description |
|---|---|
-e, --environment <slug> | (Required) The environment slug. |
Repair Envelope
Attempt a rewrap first; if that fails, fall back to a full reset.
Options
| Flag | Description |
|---|---|
-e, --environment <slug> | (Required) The environment slug. |
--old-key-path <path> | (Required) Path to the old private key PEM file. |
--old-device-key-id <id> | (Required) The ID of the old device key. |
Managing Applications
List Applications
View all applications available to your account:
Each entry displays the application name and ID.
Tips
- Run
secret-stash --helpto see all top-level commands. - Run
secret-stash <command> --helpto see options for a specific command (e.g.,secret-stash variables --help). - In CI, provide
SECRET_STASH_API_TOKENandSECRET_STASH_APPLICATION_IDvia your platform's secret store.