Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.barekey.dev/llms.txt

Use this file to discover all available pages before exploring further.

This quickstart uses the actual shipped workflow:
  1. Install and log into the CLI.
  2. Run barekey init.
  3. Create a variable.
  4. Read it with @barekey/sdk/server.

​
Prerequisites

  • Node.js 18+ or Bun
  • a Barekey account

​
1. Install the CLI

npm install -g @barekey/cli
Log in: 
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 install @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.