Programmatic Usage

Use the SecretStash Node module as a project dependency for programmatic access to the SecretStash API.

When installed as a project dependency, the SecretStash Node module exposes a full TypeScript API for managing variables, device keys, envelopes, and applications programmatically. This is ideal for custom build scripts, server-side integrations, and automation workflows.

Installation

npm install @secret-stash/cli --save

Client Setup

All API interactions go through the SecretStashClient class. By default, it reads credentials from environment variables or your .env file:

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

// Uses SECRET_STASH_API_TOKEN and SECRET_STASH_API_URL from the environment
const client = new SecretStashClient();

You can also pass configuration directly:

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

If constructor arguments are omitted, the client resolves configuration from system environment variables, then the .env file, then defaults. See Configuration for details.

Managing Variables

The VariablesManager handles listing, pulling, and pushing environment variables.

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

const client = new SecretStashClient();
const variables = new VariablesManager();

Listing Variables

Retrieve a masked list of variables for an environment:

const result = await variables.list(client, "your-app-id", "production");

console.log(`Total variables: ${result.total}`);
for (const v of result.variables) {
  console.log(`${v.name} = ${v.maskedValue}`);
}

Returns ListVariablesResult:

Property	Type	Description
`variables`	`Array`	List of variables with `id`, `name`, `maskedValue`, and `created_at`.
`total`	`number`	Total number of variables.

Pulling Variables

Decrypt and merge remote variables into a local .env file:

const result = await variables.pull(client, "your-app-id", "production", ".env");

console.log(`Pulled ${result.variableCount} variables into ${result.filePath}`);

Parameters:

Parameter	Type	Default	Description
`client`	`SecretStashClient`	—	The API client.
`applicationId`	`string`	—	Your application ID.
`environmentSlug`	`string`	—	The environment slug (e.g., `production`).
`filePath`	`string`	`".env"`	Path to the `.env` file to update.

Returns PullVariablesResult:

Property	Type	Description
`filePath`	`string`	The path to the updated `.env` file.
`variableCount`	`number`	Number of variables written.

Pushing Variables

Encrypt and upload local .env variables to SecretStash:

const result = await variables.push(client, "your-app-id", "production", ".env");

console.log(`Pushed ${result.created} variables. Failed: ${result.failed}`);

Parameters:

Parameter	Type	Default	Description
`client`	`SecretStashClient`	—	The API client.
`applicationId`	`string`	—	Your application ID.
`environmentSlug`	`string`	—	The environment slug.
`filePath`	`string`	`".env"`	Path to the `.env` file to read.

Returns PushVariablesResult:

Property	Type	Description
`created`	`number`	Number of variables successfully pushed.
`failed`	`number`	Number of variables that failed to push.

Push is blocked for environments with the testing type. This restriction is enforced at both the client and API level.

Managing Device Keys

The KeyManager handles local RSA key pair generation, registration, and recovery.

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

const client = new SecretStashClient();
const keys = new KeyManager();

You can optionally pass a custom key directory:

const keys = new KeyManager("/path/to/custom/key/dir");

Initializing a Device Key

Generate and register a new RSA-4096 key pair:

const result = await keys.init(client, {
  label: "My Node Server",
  force: false,
});

console.log(`Key ID: ${result.deviceKeyId}`);
console.log(`Fingerprint: ${result.fingerprint}`);
console.log(`Key directory: ${result.keyDirectory}`);

Options (KeyInitOptions):

Property	Type	Default	Description
`label`	`string`	hostname	A human-readable label for this device.
`force`	`boolean`	`false`	Force regeneration of existing keys.
`temporary`	`boolean`	`false`	Create a short-lived key for CI/CD.
`ttlMinutes`	`number`	`15`	TTL in minutes for temporary keys.

Returns KeyInitResult:

Property	Type	Description
`deviceKeyId`	`number`	The server-assigned device key ID.
`label`	`string`	The device label.
`fingerprint`	`string`	SHA-256 fingerprint of the public key.
`keyDirectory`	`string`	Path to the key storage directory.
`isTemporary`	`boolean`	Whether this is a temporary key.
`expiresAt`	`string \| null`	Expiration timestamp for temporary keys.

Checking Key Status

const status = await keys.status(client);

console.log(`Local key found: ${status.hasLocalPrivateKey}`);
console.log(`Registered on server: ${status.isRegisteredOnServer}`);
console.log(`Server keys: ${status.serverKeyCount}`);

Syncing Device Metadata

const meta = await keys.sync(client);

console.log(`Key ID: ${meta.device_key_id}`);
console.log(`Fingerprint: ${meta.fingerprint}`);

Generating a Recovery Key

const recovery = await keys.generateRecoveryKey(client, {
  outputDir: "./recovery",
  force: false,
});

console.log(`Recovery share saved to: ${recovery.sharePath}`);

Managing Environments

The EnvironmentsManager handles listing and creating environments.

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

const client = new SecretStashClient();
const environments = new EnvironmentsManager();

Listing Environments

const result = await environments.list(client, "your-app-id");

for (const env of result.environments) {
  console.log(`${env.name} (${env.slug}) — ${env.type}`);
}

Creating an Environment

const result = await environments.create(
  client,
  "your-app-id",
  "Staging",      // name
  "staging",      // slug
  "development"   // type
);

console.log(`Created: ${result.name} (${result.slug})`);

Managing Envelopes

The EnvelopeManager handles envelope rewrapping, repair, and reset operations.

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

const client = new SecretStashClient();
const envelopes = new EnvelopeManager();

Rewrapping an Envelope

Migrate access from an old device key to your current device key:

await envelopes.rewrap(client, {
  applicationId: "your-app-id",
  environmentSlug: "production",
  oldPrivateKeyPath: "/path/to/old/device_private_key.pem",
  oldDeviceKeyId: 42,
});

Resetting Envelopes

Generate a new DEK and create envelopes for all registered devices:

const result = await envelopes.reset(client, "your-app-id", "production");

console.log(`Created ${result.envelopeCount} envelopes`);

Repairing an Envelope

Attempt a rewrap; if that fails, fall back to a full reset:

await envelopes.repair(client, {
  applicationId: "your-app-id",
  environmentSlug: "production",
  oldPrivateKeyPath: "/path/to/old/device_private_key.pem",
  oldDeviceKeyId: 42,
});

Managing Applications

The ApplicationsManager provides read access to your available applications.

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

const client = new SecretStashClient();
const apps = new ApplicationsManager();

const result = await apps.list(client);

for (const app of result.applications) {
  console.log(`${app.name} (${app.id})`);
}

Error Handling

The module throws typed errors that you can catch and handle:

Error Class	Description
`InvalidApiToken`	The API token is invalid or expired.
`MissingApiToken`	No API token was configured.
`InvalidEnvironmentConfiguration`	Required configuration is missing or invalid.
`NoEnvironmentsFound`	The specified environment does not exist.
`DeviceKeyNotRegistered`	No local device key found or key not registered on server.
`PrivateKeyNotFound`	The local private key file is missing.
`PrivateKeyFailedToSave`	Failed to save the private key to disk.
`MetaKeyFailedToSave`	Failed to save the device metadata file.

import { SecretStashClient, VariablesManager, InvalidApiToken, NoEnvironmentsFound } from "@secret-stash/cli";

try {
  const client = new SecretStashClient();
  const variables = new VariablesManager();
  await variables.pull(client, "app-id", "production");
} catch (error) {
  if (error instanceof InvalidApiToken) {
    console.error("Check your SECRET_STASH_API_TOKEN");
  } else if (error instanceof NoEnvironmentsFound) {
    console.error("Environment not found:", error.message);
  } else {
    throw error;
  }
}

Exported Types

The module also exports the following TypeScript types for use in your application:

Type	Description
`KeyInitOptions`	Options for `KeyManager.init()`.
`KeyStatusResult`	Return type of `KeyManager.status()`.
`KeyInitResult`	Return type of `KeyManager.init()`.
`RecoveryKeyResult`	Return type of `KeyManager.generateRecoveryKey()`.
`ListVariablesResult`	Return type of `VariablesManager.list()`.
`PullVariablesResult`	Return type of `VariablesManager.pull()`.
`PushVariablesResult`	Return type of `VariablesManager.push()`.
`ListEnvironmentsResult`	Return type of `EnvironmentsManager.list()`.
`CreateEnvironmentResult`	Return type of `EnvironmentsManager.create()`.
`ListApplicationsResult`	Return type of `ApplicationsManager.list()`.
`RewrapOptions`	Options for `EnvelopeManager.rewrap()` and `repair()`.
`ResetResult`	Return type of `EnvelopeManager.reset()`.
`DeviceMetadata`	Device key metadata structure.
`EnvelopePayload`	Encrypted envelope structure.
`ApplicationData`	Application record from the API.
`EnvironmentData`	Environment record from the API.
`EnvironmentType`	Enum of environment types.

Node module source code: https://github.com/dniccum/secret-stash-node

Configuration

Learn how to configure the SecretStash Node module for your project.

CI/CD Integration

Learn how to use the SecretStash Node module in CI/CD pipelines with temporary device keys for safe, automated secret access.