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

# Local development

> Use Barekey locally with `barekey.json`, pulled `.env` files, or standalone SDK mode backed by local `.env` files.

Barekey supports two good local-development workflows:

1. centralized Barekey plus CLI login
2. standalone local `.env` files through the server SDK

## Workflow 1: centralized Barekey with local login

This is the most ergonomic team workflow.

### Step 1: log in once

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

### Step 2: commit `barekey.json`

```json theme={null}
{
  "organization": "acme",
  "project": "web",
  "environment": "development",
  "config": {
    "typegen": "semantic",
    "mode": "centralized"
  }
}
```

### Step 3: use either the CLI or SDK

CLI:

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

SDK:

```ts theme={null}
import { BarekeyClient } from "@barekey/sdk/server";

export const barekey = new BarekeyClient();
```

In this setup the SDK resolves:

* scope from `barekey.json`
* auth from your stored CLI login unless `BAREKEY_ACCESS_TOKEN` is set

## Workflow 2: standalone local `.env` mode

Use this when you want the Barekey SDK API but do not want network-backed reads for local work.

Set:

```json theme={null}
{
  "config": {
    "mode": "standalone"
  }
}
```

Then use:

```ts theme={null}
import { BarekeyClient } from "@barekey/sdk/server";

const barekey = new BarekeyClient({
  typegen: false,
});
```

In standalone mode the SDK reads local `.env*` files instead of calling the API.

## `barekey.json` reference

| Key              | Type                              | Required in centralized mode | Required in standalone mode | Notes                            |
| ---------------- | --------------------------------- | ---------------------------- | --------------------------- | -------------------------------- |
| `organization`   | `string`                          | Yes                          | No                          | canonical org key                |
| `project`        | `string`                          | Yes                          | No                          | project slug                     |
| `environment`    | `string`                          | Yes                          | No                          | stage name                       |
| `org`            | `string`                          | No                           | No                          | alias for `organization`         |
| `stage`          | `string`                          | No                           | No                          | alias for `environment`          |
| `config.mode`    | `"centralized"` or `"standalone"` | No                           | No                          | defaults to `"centralized"`      |
| `config.typegen` | `"semantic"` or `"minimal"`       | No                           | No                          | standalone resolves to `minimal` |

### Search behavior

Barekey searches upward from the current working directory until it finds a `barekey.json`.

That matters in monorepos because:

* one repo-root config can serve many packages
* standalone mode uses the discovered config directory as the local env root

## Pulling to `.env.local`

If your framework expects dotenv files, use:

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

Or JSON:

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

Add pulled files to `.gitignore`:

```gitignore theme={null}
.env.local
.env*.local
barekey.local.json
```

## How standalone `.env` loading behaves

The SDK reads local env files from the standalone root directory.

The tests cover patterns such as:

* `.env`
* `.env.local`
* `.env.<environment>.local`

Values are normalized into uppercase Barekey keys.

Example:

```dotenv theme={null}
# .env
database_url=postgres://root
feature_enabled=true

# .env.local
database_url=postgres://local

# .env.development.local
launch_at=2026-03-14T12:00:00.000Z
```

These can resolve like:

* `DATABASE_URL`
* `FEATURE_ENABLED`
* `DEVELOPMENT_LOCAL_LAUNCH_AT`

## Choosing between pull and standalone mode

| Approach                                         | Best for                                                       |
| ------------------------------------------------ | -------------------------------------------------------------- |
| `barekey env pull --out .env.local`              | frameworks that already load dotenv files                      |
| `BarekeyClient` with `config.mode: "standalone"` | code that wants one SDK API locally and remotely               |
| centralized SDK with CLI-session auth            | teams that want the real Barekey flow during local development |

## Production recommendation

For production, prefer centralized SDK reads with `BAREKEY_ACCESS_TOKEN`.

Use local pull files or standalone mode for local development only.