Installation

The SecretStash Node module (@secret-stash/cli) can be used in two ways:

• Global CLI: Install globally and use the secret-stash command from any directory.
• Project dependency: Install locally and import the TypeScript/JavaScript API into your application for programmatic access.

Requirements

• Node.js 18 or higher
• A SecretStash API token and Application ID

Global Installation

Install the package globally to use the secret-stash CLI from anywhere on your machine:

npm install -g @secret-stash/cli

Or run commands directly without installing using npx:

npx @secret-stash/cli --help

Initialize your device

After installing globally, initialize your device key:

secret-stash key init

This generates an RSA-4096 key pair and registers it with the SecretStash server.

Configure environment variables

Add the following to your project's .env file:

SECRET_STASH_API_TOKEN=your_token_here
SECRET_STASH_APPLICATION_ID=your_application_id_here

• API Token: Create a token in SecretStash by navigating to your profile settings and accessing the "Tokens" tab.
• Application ID: Create or select an Application in SecretStash and copy its ID from the dashboard.

Quick start

Pull your environment's variables from SecretStash into your local .env file:

secret-stash variables pull -e production

Push your local .env variables to SecretStash:

secret-stash variables push -e production

Project Dependency Installation

Install the package as a local dependency in your Node.js or TypeScript project:

npm install @secret-stash/cli --save

Configure environment variables

Add the following to your project's .env file:

SECRET_STASH_API_TOKEN=your_token_here
SECRET_STASH_APPLICATION_ID=your_application_id_here

• API Token: Create a token in SecretStash by navigating to your profile settings and accessing the "Tokens" tab.
• Application ID: Create or select an Application in SecretStash and copy its ID from the dashboard.

Use the CLI via npx

When installed as a project dependency, run CLI commands via npx:

npx secret-stash key init
npx secret-stash variables pull -e production

Use the programmatic API

Import the module directly into your TypeScript or JavaScript code for full programmatic control:

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

const client = new SecretStashClient();
const keyManager = new KeyManager();
const variablesManager = new VariablesManager();

// Pull variables from SecretStash into a local .env file
const result = await variablesManager.pull(client, "your-app-id", "production");
console.log(`Pulled ${result.variableCount} variables into ${result.filePath}`);

See Programmatic Usage for the full API reference.

Next Steps

• Explore all CLI commands in the commands reference.
• Learn about configuration options.
• Use the programmatic API for custom integrations.
• Set up CI/CD integration for automated pipelines.