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

# Stages

> Stages are the environment boundary in Barekey. They decide which variable set your CLI and SDK target.

A stage is an environment inside a project, such as:

* `development`
* `staging`
* `production`

Variables are isolated per stage. The same key name can exist in multiple stages with different values.

## Why stages matter

If you store:

* `DATABASE_URL` in `development`
* `DATABASE_URL` in `production`

those are two separate variables with separate values.

Changing one does not affect the other.

## How the CLI targets a stage

The CLI resolves the stage from:

1. `--stage`
2. `barekey.json`

Example:

```bash theme={null}
barekey env list --stage production
barekey env pull --stage staging --out .env.staging
```

## How the SDK targets a stage

With explicit configuration:

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

const barekey = new BarekeyClient({
  organization: "acme",
  project: "api",
  environment: "production",
});
```

Or through `barekey.json`:

```json theme={null}
{
  "organization": "acme",
  "project": "api",
  "environment": "production"
}
```

## Good stage habits

* keep `development`, `staging`, and `production` values separate
* commit `barekey.json` so teammates target the same default stage
* use `--stage` explicitly in scripts when the target matters
* use production tokens and production stages carefully