BKey CLI

Installation

Requires Node.js 22.12 or newer.

npm install -g @bkey/cli

First-time setup

# 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

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:

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 clients list [--all]`	List the Login with bkey OAuth clients you own.
`bkey clients create --name <n> --redirect-uri <uri...> [--public] [--no-vault]`	Register a client owned by you; the secret is shown once and pushed to your phone’s vault.
`bkey clients get <id>` / `update <id> …` / `revoke <id>`	Read, edit (name, redirect URIs, post-logout URIs, id_token alg), and revoke.
`bkey clients rotate-secret <id> [--grace-hours <n>] [--no-vault]`	New secret (shown once, vaulted); old one keeps working for the grace period.
`bkey clients analytics <id>`	Started vs completed sign-ins over 7 / 30 days.
`bkey clients enable-personas <id>` / `logo <id> <png>` / `claim <id> --registration-access-token <t>`	Per-site personas (permanent), logo upload, and claiming an anonymously registered client.
`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 clients` — the developer dashboard, headless

Everything the bkey.id/developers dashboard does for “Login with bkey” is available from the terminal, so an agent working on your machine can set up and operate your integration for you the way flyctl operates a Fly app. Client management is owner-scoped to the signed-in human (bkey auth login); agent client_credentials tokens are rejected, and every command accepts --json.

# Register a confidential client for your app. The secret prints once AND is
# sent end-to-end encrypted to your phone's vault (one approval on the phone).
bkey clients create --name "Brain15 (dev)"   --redirect-uri https://dev.brain15.example/api/auth/callback/bkey   --post-logout-redirect-uri https://dev.brain15.example/

# Use the secret later without it ever appearing in a transcript:
bkey wrap --env BKEY_CLIENT_SECRET="{vault:Brain15 (dev) · Login with bkey}" -- npm run dev

bkey clients list
bkey clients analytics bkey_client_xxx
bkey clients update bkey_client_xxx --redirect-uri https://dev.brain15.example/api/auth/callback/bkey https://brain15.example/api/auth/callback/bkey
bkey clients rotate-secret bkey_client_xxx --grace-hours 24
bkey clients revoke bkey_client_xxx --yes

--public registers a PKCE-only client (no secret) for SPAs and native apps. --no-vault skips the phone push on create and rotate-secret; the secret is then printed once and not stored anywhere. A rotation that times out may still have completed on the server — check whether the old secret still works before rotating again.

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

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

​BKey CLI

​Installation

​First-time setup

​Biometric approval from the terminal

​Commands

​bkey clients — the developer dashboard, headless

​bkey wrap — inject vault secrets into a process

​Source