Local development

Barekey supports two good local-development workflows:

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

This is the most ergonomic team workflow.

Step 1: log in once

barekey auth login

Step 2: commit `barekey.json`

{
  "organization": "acme",
  "project": "web",
  "environment": "development",
  "config": {
    "typegen": "semantic",
    "mode": "centralized"
  }
}

Step 3: use either the CLI or SDK

CLI:

barekey env list
barekey env get DATABASE_URL
barekey env pull --out .env.local

SDK:

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:

{
  "config": {
    "mode": "standalone"
  }
}

Then use:

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:

barekey env pull --out .env.local

Or JSON:

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

Add pulled files to .gitignore:

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

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

Getting started

Core concepts

SDK and CLI

Barekey vs alternatives

Local development

Step 1: log in once

Step 2: commit `barekey.json`

Step 3: use either the CLI or SDK

Workflow 2: standalone local `.env` mode

`barekey.json` reference

Search behavior

Pulling to `.env.local`

How standalone `.env` loading behaves

Choosing between pull and standalone mode

Production recommendation

​Workflow 1: centralized Barekey with local login

​Step 1: log in once

​Step 2: commit barekey.json

​Step 3: use either the CLI or SDK

​Workflow 2: standalone local .env mode

​barekey.json reference

​Search behavior

​Pulling to .env.local

​How standalone .env loading behaves

​Choosing between pull and standalone mode

​Production recommendation

Workflow 1: centralized Barekey with local login

Step 1: log in once

Step 2: commit `barekey.json`

Step 3: use either the CLI or SDK

Workflow 2: standalone local `.env` mode

`barekey.json` reference

Search behavior

Pulling to `.env.local`

How standalone `.env` loading behaves

Choosing between pull and standalone mode

Production recommendation