Skip to main content
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

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

KeyTypeRequired in centralized modeRequired in standalone modeNotes
organizationstringYesNocanonical org key
projectstringYesNoproject slug
environmentstringYesNostage name
orgstringNoNoalias for organization
stagestringNoNoalias for environment
config.mode"centralized" or "standalone"NoNodefaults to "centralized"
config.typegen"semantic" or "minimal"NoNostandalone 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

ApproachBest for
barekey env pull --out .env.localframeworks that already load dotenv files
BarekeyClient with config.mode: "standalone"code that wants one SDK API locally and remotely
centralized SDK with CLI-session authteams 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.