Getting started with Secrets

Install

Secrets is included in @cipherstash/stack:

npm install @cipherstash/stack

Prerequisites

• Node.js >= 18
• CipherStash initialized — complete the Getting started guide first

Store a secret

For local development, device-based auth handles credentials automatically:

import { Secrets } from "@cipherstash/stack/secrets"

const secrets = new Secrets({
  environment: "development",
})

await secrets.set("DATABASE_URL", "postgres://user:pass@host:5432/db")

The value is encrypted locally before being sent to the CipherStash API. Your plaintext secret never leaves your application.

const secrets = new Secrets({
  workspaceCRN: process.env.CS_WORKSPACE_CRN!,
  clientId: process.env.CS_CLIENT_ID!,
  clientKey: process.env.CS_CLIENT_KEY!,
  accessKey: process.env.CS_CLIENT_ACCESS_KEY!,
  environment: "production",
})

Retrieve a secret

const result = await secrets.get("DATABASE_URL")

if (!result.failure) {
  console.log(result.data) // "postgres://user:pass@host:5432/db"
}

The encrypted value is fetched from the API and decrypted locally.

Using the CLI

You can also manage secrets from the terminal without writing code. Device-based auth means no credential flags are needed locally:

npx @cipherstash/cli secrets set --name DATABASE_URL --value "postgres://..." --environment development
npx @cipherstash/cli secrets get --name DATABASE_URL --environment development

See the CLI reference for all available commands.

Environments and keysets

The environment parameter maps to a keyset in CipherStash Cloud. Each environment gets its own cryptographic boundary — secrets encrypted in development cannot be decrypted with production keys.

You can manage environments in the Dashboard under Vault > Environments. Creating an environment either creates a new keyset or uses an existing one.

Next steps

• Learn about core concepts like workspaces and environments
• See the full SDK reference for all operations
• Use the CLI reference for terminal-based management