quickstart.mdx

title	Quickstart
description	Install the CLI, run barekey init, create a variable, and read it with the Barekey SDK.

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

```bash npm install -g @barekey/cli ``` ```bash pnpm add -g @barekey/cli ``` ```bash yarn global add @barekey/cli ``` ```bash bun add -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

```bash npm install @barekey/sdk ``` ```bash pnpm add @barekey/sdk ``` ```bash yarn add @barekey/sdk ``` ```bash 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

Full server SDK, public SDK, standalone mode, typegen, and config reference. Full command reference with flags, examples, and output formats. `barekey.json`, `.env` pull workflows, and standalone local reads. Understand `secret` and `ab_roll`.