> ## Documentation Index
> Fetch the complete documentation index at: https://bkey.id/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> @bkey/cli — biometric approval and vault access from the terminal.

# BKey CLI

## Installation

```bash theme={null}
npm install -g @bkey/cli
```

## First-time setup

```bash theme={null}
# Log in with QR code (device authorization)
bkey auth login

# Create agent credentials for a program that will request approvals
bkey auth setup-agent --name "My Agent" --save
```

`setup-agent --save` stores the new agent as a named profile in `~/.bkey/profiles.json` alongside your human session. The profile identifier is slugified from `--name` (`"My Agent"` → `my-agent`); override with `--profile <slug>`. Agent mode is opt-in — invoke with `--agent` (uses the default agent profile) or `--agent --profile my-agent` (pin a specific one). List all profiles with `bkey profiles`.

## Biometric approval from the terminal

```bash theme={null}
bkey approve "Deploy api-gateway@abc123 to production" \
  --scope approve:deploy \
  --user-did did:bkey:...
```

Blocks until the user approves on their phone. Exits 0 on approval, non-zero on denial or timeout. Pipe it to gate any shell command:

```bash theme={null}
bkey approve "Run db migration 0042" --scope approve:action && \
  ./scripts/migrate.sh
```

Add `--json` to get the full approval token on stdout for downstream use. Add `--amount`, `--currency`, `--resource`, `--recipient`, `--description` to render structured details on the approval screen.

## Commands

| Command                                                              | Description                                                                       |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `bkey auth login [--profile <name>]`                                 | Device auth flow (QR code). Creates/updates a named human profile.                |
| `bkey auth setup-agent --save [--name <display>] [--profile <slug>]` | Create agent OAuth client + save as a named profile.                              |
| `bkey auth status [--agent] [--profile <name>]`                      | Show current auth status for the selected principal + profile.                    |
| `bkey auth logout [--agent] [--profile <name>] [--all]`              | Revoke the active (or named) profile's tokens.                                    |
| `bkey profiles`                                                      | List all profiles (humans + agents). `ls` alias.                                  |
| `bkey profiles use <name> [--agent]`                                 | Set the default profile for that principal.                                       |
| `bkey profiles rename <old> <new> [--agent]`                         | Rename a profile.                                                                 |
| `bkey profiles delete <name> [--agent]`                              | Delete a profile.                                                                 |
| `bkey approve <msg>`                                                 | Generic CIBA approval (agent-only).                                               |
| `bkey vault store <name>`                                            | Store a secret with end-to-end encryption.                                        |
| `bkey vault access <name>`                                           | Request a stored secret (biometric-approved).                                     |
| `bkey checkout request`                                              | Initiate a checkout approval.                                                     |
| `bkey checkout status <id>`                                          | Poll a checkout.                                                                  |
| `bkey proxy <url>`                                                   | HTTP proxy that handles 402 payments automatically.                               |
| `bkey wrap -- <cmd>`                                                 | Run a command with vault secrets injected as env vars (biometric-approved reads). |

Dual-mode commands (`vault`, `proxy`, `wrap`, `checkout`) accept `--agent` / `--human` / `--profile <name>`. `BKEY_PROFILE` and `BKEY_MODE=agent` env vars work for shell workflows.

## `bkey wrap` — inject vault secrets into a process

Run any program with vault-backed environment variables. Each `{vault:name}` placeholder triggers a biometric approval on the user's phone before the command starts, and the decrypted value is delivered end-to-end to the CLI process:

```bash theme={null}
bkey wrap --env OPENAI_API_KEY={vault:openai-api-key} -- \
  python my_agent.py
```

The value is never written to disk. If the user denies, the wrapped command never runs.

## Source

[github.com/bkeyID/bkey/typescript/packages/cli](https://github.com/bkeyID/bkey/tree/main/typescript/packages/cli)