@heizen-labs/secrets-sdk

Lightweight SDK to fetch secrets from Heizen Studio and load them into your runtime environment.

Install

npm install @heizen-labs/secrets-sdk
# or
pnpm add @heizen-labs/secrets-sdk
# or
bun add @heizen-labs/secrets-sdk

Quick Start

import { SecretsClient } from "@heizen-labs/secrets-sdk";

const client = new SecretsClient({
  projectId: "proj_123",
  environment: "development",
  apiKey: process.env.HEIZEN_STUDIO_API_KEY ?? "",
});

await client.loadSecrets();

console.log(process.env.DATABASE_URL);

CLI: run command with injected secrets

The package also provides a heizen-secrets CLI binary.

heizen-secrets run <projectId> <environment> [--api-key <key>] [--base-url <url>] [--override] -- <command> [args...]

Example:

heizen-secrets run proj_11 development -- nest start --watch

With explicit API key:

heizen-secrets run proj_11 development --api-key xxx -- pnpm dev

Behavior and guarantees:

• Secrets are fetched and injected only into the spawned process environment.
• Secrets are never printed, written to files, or exported by the CLI.
• Parent process env is not mutated.
• API key lookup order: --api-key -> process.env.HEIZEN_STUDIO_API_KEY -> .env.local -> .env.

Limitation:

• Your application can still read and print its own environment values if your code chooses to do that.

How to get HEIZEN_STUDIO_API_KEY

1. Go to https://studio.heizen.work.
2. Open your project.
3. Go to Project Settings.
4. Create a new API key.
5. Grant secrets:read permission.
6. Save the key and set it as HEIZEN_STUDIO_API_KEY in your environment.

App Script Integration

In your app package.json:

{
  "scripts": {
    "dev": "heizen-secrets run proj_11 development -- nest start --watch"
  }
}

API Reference

new SecretsClient(options)

| Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | projectId | string | Yes | - | Heizen project ID (example: proj_123) | | environment | string | Yes | - | Environment name (example: development, production) | | apiKey | string | Yes | - | API key sent as x-api-key | | baseUrl | string | No | https://api.studio.heizen.work | Override API host | | axiosInstance | AxiosInstance | No | internal instance | Custom axios config/interceptors |

client.loadSecrets(options?): Promise<Record<string, string>>

Fetches secrets and writes them into an env-like target object.

| Option | Type | Default | Description | | --- | --- | --- | --- | | override | boolean | false | If true, replaces existing values in target | | target | Record<string, string \| undefined> | process.env | Target object where secrets are written |

loadSecrets Examples

// Default: writes into process.env, does not overwrite existing keys
await client.loadSecrets();

// Overwrite existing process.env keys
await client.loadSecrets({ override: true });

// Write into a custom object
const envObject: Record<string, string | undefined> = {};
await client.loadSecrets({ target: envObject });

Errors

All SDK errors are thrown as SecretsClientError.

import { SecretsClientError } from "@heizen-labs/secrets-sdk";

try {
  await client.loadSecrets();
} catch (error) {
  if (error instanceof SecretsClientError) {
    console.error(error.message, error.status);
  }
}