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

# CLI

> Full Barekey CLI guide, including login, target resolution, `barekey.json`, environment commands, pull workflows, and type generation.

The Barekey CLI is the fastest way to work with Barekey day to day.

Use it to:

* log in on a machine
* create, update, list, and delete variables
* pull resolved values into files
* generate SDK types

## Install

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

## Authentication

### `barekey auth login`

Starts the browser-based device flow:

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

Optional:

```bash theme={null}
barekey auth login --base-url https://api.barekey.dev
```

What it does:

* starts a device authorization request
* prints the verification URL and code
* opens the browser when possible
* stores the session locally after approval

### `barekey auth whoami`

```bash theme={null}
barekey auth whoami
barekey auth whoami --json
```

### `barekey auth logout`

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

Top-level aliases also exist:

* `barekey login`
* `barekey whoami`
* `barekey logout`

## How target resolution works

Every environment command needs a target:

* organization
* project
* stage

The CLI resolves those from:

1. command flags
2. `barekey.json`
3. stored CLI session org for organization only

### Target flags

Most `env` and `typegen` commands accept:

```bash theme={null}
--org <slug>
--project <slug>
--stage <slug>
```

### `barekey.json`

Recommended project file:

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

Supported aliases:

* `org` for `organization`
* `stage` for `environment`

### Missing target errors

If the CLI cannot resolve `project` and `environment`, it fails and tells you to either:

* pass `--project` and `--stage`
* or create a `barekey.json`

## Command reference

## `barekey env list`

List variables in the resolved stage:

```bash theme={null}
barekey env list
barekey env list --json
```

The non-JSON output includes:

* name
* visibility
* kind
* declared type

## `barekey env get`

Read one resolved variable:

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

Options:

```bash theme={null}
barekey env get CHECKOUT_FLOW --seed user-42 --key checkout-v1
barekey env get DATABASE_URL --json
```

Flags:

| Flag             | Meaning                          |
| ---------------- | -------------------------------- |
| `--seed <value>` | deterministic seed for `ab_roll` |
| `--key <value>`  | deterministic namespace key      |
| `--json`         | machine-readable output          |

## `barekey env get-many`

Read multiple values in one command:

```bash theme={null}
barekey env get-many --names DATABASE_URL,REDIS_URL
barekey env get-many --names DATABASE_URL,REDIS_URL --json
```

Flags:

| Flag             | Meaning                                 |
| ---------------- | --------------------------------------- |
| `--names <csv>`  | comma-separated variable names          |
| `--seed <value>` | deterministic seed for `ab_roll` values |
| `--key <value>`  | deterministic namespace key             |
| `--json`         | machine-readable output                 |

## `barekey env new`

Create a variable with its first value:

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

Flags:

| Flag                        | Meaning                                                                                |
| --------------------------- | -------------------------------------------------------------------------------------- |
| `--type <type>`             | declared type: `string`, `boolean`, `int64`, `float`, `date`, `json`                   |
| `--visibility <visibility>` | `private` or `public`                                                                  |
| `--ab <value-b>`            | create an `ab_roll` with A value from the positional `<value>` and B value from `--ab` |
| `--chance <number>`         | required when using `--ab`, from `0` to `1`                                            |
| `--json`                    | machine-readable output                                                                |

Example:

```bash theme={null}
barekey env new FEATURE_ENABLED true --type boolean
barekey env new PUBLIC_TITLE "Barekey" --visibility public
barekey env new CHECKOUT_FLOW original --ab redesigned --chance 0.2
```

## `barekey env set`

Upsert a variable:

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

This creates the variable if it does not exist and updates it if it does.

It accepts the same flags as `env new`.

Examples:

```bash theme={null}
barekey env set FEATURE_ENABLED false --type boolean
barekey env set CHECKOUT_FLOW control --ab treatment --chance 0.5
barekey env set PUBLIC_TITLE "Barekey Docs" --visibility public
```

## `barekey env delete`

Delete a variable:

```bash theme={null}
barekey env delete OLD_KEY
```

Flags:

| Flag               | Meaning                                    |
| ------------------ | ------------------------------------------ |
| `--yes`            | skip the confirmation prompt               |
| `--ignore-missing` | do not fail if the variable does not exist |
| `--json`           | machine-readable output                    |

Examples:

```bash theme={null}
barekey env delete OLD_KEY --yes
barekey env delete OLD_KEY --yes --ignore-missing
```

## `barekey env pull`

Resolve the whole stage and either print or write the result.

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

Flags:

| Flag              | Meaning                                                         |
| ----------------- | --------------------------------------------------------------- |
| `--format <type>` | `dotenv` or `json`                                              |
| `--out <path>`    | write to a file instead of stdout                               |
| `--seed <value>`  | deterministic seed for `ab_roll` values                         |
| `--key <value>`   | deterministic namespace key                                     |
| `--redact`        | if printing to stdout in a non-TTY context, show only a summary |

Examples:

```bash theme={null}
barekey env pull --out .env.local
barekey env pull --format json --out barekey.local.json
barekey env pull --seed user-42 --key checkout-v1 --out .env.local
```

### Output formats

`dotenv`:

```dotenv theme={null}
DATABASE_URL=postgres://localhost:5432/app
FEATURE_ENABLED=true
```

`json`:

```json theme={null}
{
  "DATABASE_URL": "postgres://localhost:5432/app",
  "FEATURE_ENABLED": "true"
}
```

## `barekey typegen`

Generate SDK types into your installed `@barekey/sdk` package:

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

Watch mode:

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

Flags:

| Flag               | Meaning                                 |
| ------------------ | --------------------------------------- |
| `--watch`          | keep polling and regenerate when needed |
| `--interval <ms>`  | watch poll interval in milliseconds     |
| `--org <slug>`     | override organization                   |
| `--project <slug>` | override project                        |
| `--stage <slug>`   | override stage                          |

## Day-to-day recipes

### Create a variable and verify it

```bash theme={null}
barekey env new DATABASE_URL "postgres://localhost:5432/app" --type string
barekey env get DATABASE_URL
```

### Update a public variable

```bash theme={null}
barekey env set PUBLIC_TITLE "Barekey Docs" --visibility public
```

### Pull local dev values

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

### Pull JSON for scripts

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

### Regenerate SDK types after variable changes

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

## Notes and gotchas

* `env new` requires an initial `<value>`.
* `env set` is the upsert command.
* `get-many` expects a comma-separated `--names` value.
* The CLI can reuse your saved login automatically.
* `barekey.json` is safe to commit because it contains configuration, not secrets.
* Pulled `.env` files are not safe to commit.

For SDK usage details, read [JavaScript SDK](/integrations/javascript-sdk).