Configuration

The SecretStash Node module resolves configuration using the following priority order:

1. Constructor arguments (programmatic usage only — highest priority)
2. System environment variables
3. .env file in the current working directory
4. Default values

This means you can configure the module entirely through your project's .env file, by exporting environment variables in your shell, or by passing values directly when constructing the client programmatically.

Environment Variables

The following environment variables are supported:

API Token

Your personal API token for authenticating with the SecretStash API. Generate a token in the SecretStash web application under Profile → Tokens.

SECRET_STASH_API_TOKEN=your_token_here

Application ID

The unique application ID supplied by the SecretStash service. This identifies which application's variables the CLI or API should interact with.

SECRET_STASH_APPLICATION_ID=your_application_id_here

When using the CLI, you can also override this per-command with the -a or --application flag:

secret-stash -a <app-id> variables list -e production

API URL

The base URL for your SecretStash API instance:

SECRET_STASH_API_URL=https://secretstash.cloud

Key Directory Override

By default, the SecretStash Node module stores device keys and metadata in the ~/.secret-stash/ directory. You can override this path by setting the SECRET_STASH_KEY_DIR environment variable:

export SECRET_STASH_KEY_DIR=/path/to/custom/key/directory

When SECRET_STASH_KEY_DIR is set, all SecretStash commands and programmatic API calls will read device keys from the specified directory instead of ~/.secret-stash/.

This is primarily useful for temporary device keys in CI/CD pipelines. When you run secret-stash key init --temporary, the module generates keys into an isolated /tmp directory and prints the SECRET_STASH_KEY_DIR export line. Setting this variable in subsequent pipeline steps allows those commands to locate the temporary keys.

Ignored Variables

The following variables are always ignored when pushing to or pulling from SecretStash:

• Any variable starting with the SECRET_STASH_ prefix
• APP_KEY
• APP_ENV

These defaults are built into the module and cannot be customized via a configuration file.

Programmatic Configuration

When using the module as a project dependency, you can pass configuration values directly to the SecretStashClient constructor:

import { SecretStashClient } from "@secret-stash/cli";

const client = new SecretStashClient(
  "https://secretstash.cloud",  // API URL (optional)
  "your_api_token_here"         // API token (optional)
);

If constructor arguments are omitted, the client falls back to the standard resolution order (environment variables → .env file → defaults). See Programmatic Usage for the full API reference.