Quickstart

This quickstart uses the actual shipped workflow:

Install and log into the CLI.
Run barekey init.
Create a variable.
Read it with @barekey/sdk/server.

Prerequisites

Node.js 18+ or Bun
a Barekey account

1. Install the CLI

npm
pnpm
yarn
bun

npm install -g @barekey/cli

pnpm add -g @barekey/cli

yarn global add @barekey/cli

bun add -g @barekey/cli

barekey login

Check the session:

barekey whoami

2. Run `barekey init`

In your project root, run:

barekey init

This walks you through org, project, and stage selection and writes barekey.json for you. The generated file looks like this:

{
  "$schema": "./node_modules/@barekey/sdk/dist/barekey.schema.json",
  "organization": "acme",
  "project": "web",
  "environment": "development",
  "config": {
    "mode": "centralized",
    "typegen": "semantic",
    "disallow_ambigious_keys": true
  }
}

Barekey also accepts the aliases org and stage, but the canonical keys are:

organization
project
environment

Once this file exists, most CLI commands and SDK clients can resolve the target automatically.

3. Create a variable

Create a variable with an initial value:

barekey env new DATABASE_URL "postgres://localhost:5432/app" --type string

If you omit arguments in an interactive terminal, Barekey can prompt you step by step instead. Read it back:

barekey env get DATABASE_URL

Update it later with env set:

barekey env set DATABASE_URL "postgres://localhost:5432/app_v2"

4. Install the SDK

npm
pnpm
yarn
bun

npm install @barekey/sdk

pnpm add @barekey/sdk

yarn add @barekey/sdk

bun add @barekey/sdk

5. Read the variable in code

Create a shared client:

import { BarekeyClient } from "@barekey/sdk/server";

export const barekey = new BarekeyClient();

Because barekey.json is present, the client can resolve:

organization
project
environment

And because you already logged in with the CLI, the SDK can reuse the local CLI session for auth during local development. Read your variable:

import { barekey } from "./barekey";

const databaseUrl = await barekey.get("DATABASE_URL");
console.log(databaseUrl);

If you want stronger startup guarantees, pass a schema directly:

import { z } from "zod";
import { BarekeyClient } from "@barekey/sdk/server";

const barekey = new BarekeyClient({
  requirements: z.object({
    DATABASE_URL: z.string().url(),
  }),
});

await barekey.get("DATABASE_URL") returns the parsed value for the variable’s declared type. If you want metadata too, use inspect():

const result = await barekey.get("DATABASE_URL").inspect();

console.log(result.value);
console.log(result.rawValue);
console.log(result.kind);
console.log(result.visibility);

6. Generate SDK types

Run:

barekey typegen

This updates generated types inside your installed @barekey/sdk package so known keys become typed in your editor. In development, you can keep it fresh:

barekey typegen --watch

7. Optional: pull to `.env.local`

If your local workflow still expects a dotenv file:

barekey env pull --out .env.local

Or JSON:

barekey env pull --format json --out barekey.local.json

Pulled files contain plaintext values. Add them to .gitignore.

What next

SDK guide

Full server SDK, public SDK, standalone mode, typegen, and config reference.

CLI guide

Full command reference with flags, examples, and output formats.

Local development

barekey.json, .env pull workflows, and standalone local reads.

Variable kinds

Understand secret and ab_roll.

Getting started

Core concepts

SDK and CLI

Barekey vs alternatives

Prerequisites

1. Install the CLI

2. Run `barekey init`

3. Create a variable

4. Install the SDK

5. Read the variable in code

6. Generate SDK types

7. Optional: pull to `.env.local`

What next

SDK guide

CLI guide

Local development

Variable kinds

​Prerequisites

​1. Install the CLI

​2. Run barekey init

​3. Create a variable

​4. Install the SDK

​5. Read the variable in code

​6. Generate SDK types

​7. Optional: pull to .env.local

​What next

SDK guide

CLI guide

Local development

Variable kinds

Prerequisites

1. Install the CLI

2. Run `barekey init`

3. Create a variable

4. Install the SDK

5. Read the variable in code

6. Generate SDK types

7. Optional: pull to `.env.local`

What next