> ## 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.

# Quickstart

> 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

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install -g @barekey/cli
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add -g @barekey/cli
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn global add @barekey/cli
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={null}
    bun add -g @barekey/cli
    ```
  </Tab>
</Tabs>

Log in:

```bash theme={null}
barekey login
```

Check the session:

```bash theme={null}
barekey whoami
```

## 2. Run `barekey init`

In your project root, run:

```bash theme={null}
barekey init
```

This walks you through org, project, and stage selection and writes `barekey.json` for you.

The generated file looks like this:

```json theme={null}
{
  "$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:

```bash theme={null}
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:

```bash theme={null}
barekey env get DATABASE_URL
```

Update it later with `env set`:

```bash theme={null}
barekey env set DATABASE_URL "postgres://localhost:5432/app_v2"
```

## 4. Install the SDK

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @barekey/sdk
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @barekey/sdk
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @barekey/sdk
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={null}
    bun add @barekey/sdk
    ```
  </Tab>
</Tabs>

## 5. Read the variable in code

Create a shared client:

```ts theme={null}
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:

```ts theme={null}
import { barekey } from "./barekey";

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

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

```ts theme={null}
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()`:

```ts theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
barekey typegen --watch
```

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

If your local workflow still expects a dotenv file:

```bash theme={null}
barekey env pull --out .env.local
```

Or JSON:

```bash theme={null}
barekey env pull --format json --out barekey.local.json
```

<Warning>
  Pulled files contain plaintext values. Add them to `.gitignore`.
</Warning>

## What next

<CardGroup cols={2}>
  <Card title="SDK guide" icon="code" href="/integrations/javascript-sdk">
    Full server SDK, public SDK, standalone mode, typegen, and config reference.
  </Card>

  <Card title="CLI guide" icon="terminal" href="/integrations/cli">
    Full command reference with flags, examples, and output formats.
  </Card>

  <Card title="Local development" icon="laptop" href="/integrations/local-development">
    `barekey.json`, `.env` pull workflows, and standalone local reads.
  </Card>

  <Card title="Variable kinds" icon="shuffle" href="/concepts/variable-kinds">
    Understand `secret` and `ab_roll`.
  </Card>
</CardGroup>