Interactive CLI

Sign in to your Burrow as yourself and manage it from the terminal with ratel.

Updated Sep 29, 2026

Machines read secrets with their own keys, as described in CLI. To manage a Burrow from the terminal, sign in as yourself and open a session. You can do what your role on the Burrow allows, the same as in the browser.

Sign in#

bash
ratel login https://burrow.example.com

Your browser opens on RatelKey's sign-in. Approve there and the terminal is signed in. The sign-in appears on the Burrow's Sessions page as the CLI, with this machine's name.

When the Burrow uses its own certificate, ratel login shows its key fingerprint to check against Settings, Network. --fingerprint <fingerprint> passes it without asking. If your browser is on another device, approve there and paste the address it ends up on into the terminal; --no-browser skips opening one on this machine.

Open a session#

bash
ratel interactive

This signs you in first if you need to, then opens a prompt on the Burrow. Type a command and press Enter. Tab completes commands, projects, environments and secret names, and the up arrow brings back earlier commands. help lists every command, and help secret shows everything one of them does. A plural works too: secrets is secret.

Move into a project or environment with use, and commands act there until you move again. use .. goes up a level, use / to the top, and use - back to where you were. Any command that acts on an environment also takes --env <project/env> to act somewhere else once.

bash
use myapp/prod
secrets
secret show DATABASE_URL
secret set API_KEY --env myapp/staging

Deleting asks you to confirm first. A change that needs you to confirm it's you opens your browser to do that, then carries on.

Command

What it does

use [<project>[/<env>] | .. | / | -]

Move into a project or environment. Alone, says where you are.

whoami

Who you're signed in as, and your role.

help [<command>]

List the commands, or everything one command does.

clear

Clear the screen.

logout

Sign out of the Burrow and leave.

exit

Leave and stay signed in. Ctrl+D does the same.

Projects and environments#

Command

What it does

projects

List the projects.

project create <name>

Create a project with dev, staging and prod environments.

project rename <project> <new name>

Rename a project.

project delete <project>

Delete a project and everything in it.

envs [<project>]

List a project's environments.

env create <name> <dev|staging|prod>

Create an environment in the current project, at that stage. Give project/name to create it elsewhere.

env rename <env> <new name>

Rename an environment.

env delete <env>

Delete an environment and every value in it.

Secrets#

Secrets are named within the environment you're in. A structured secret's field is NAME.field, for example DATABASE.host.

Command

What it does

secrets [<project/env>]

List the secrets in an environment, names only.

secret show <NAME>[.field]

Show a value. The read is recorded in the audit log.

secret copy <NAME>[.field]

Copy a value to the clipboard without showing it. The clipboard is cleared after 30 seconds.

secret info <NAME>

A secret's type, fields, version and history, without its value.

secret set <NAME>[.field]

Set a value, creating the secret if it's new. You type the value at a hidden prompt.

secret create <NAME>

Create a secret, refused if the name is already taken in the project.

secret history <NAME>[.field]

List a secret's versions.

secret revert <NAME>[.field] <version>

Make an earlier version current again, as a new version.

secret rename <NAME> <new name>

Rename a secret in every environment of its project.

secret delete <NAME>

Delete a secret from this environment.

secret arm <NAME>

Arm a canary.

secret disarm <NAME>

Disarm a canary.

--version <N> shows or copies an earlier version. --file <path> takes the value from a file, for certificates and keys, and --type <type> sets a new secret's type. secret create --structured makes a secret with named fields and asks you for each one. secret create --canary makes a canary: a machine that reads it while it's armed is disabled.

bash
secret create DATABASE --structured
secret show DATABASE.host
secret set TLS_CERT --file ./cert.pem
secret revert API_KEY v3

Command

What it does

shares <NAME>

List a secret's live share links.

share create <NAME>

Make a share link to a secret. The link is shown once.

share revoke <NAME> <id>

Revoke a share link.

A link opens once and lives 24 hours unless you say otherwise: --views <N> and --expires <30m|12h|7d>. --passphrase also requires a passphrase, which you send separately, and --members-only opens it only for this Burrow's members.

bash
share create API_KEY --views 2 --expires 1h

Machine access#

Command

What it does

access [<project>]

The machines that can read a project, and which stages.

access grant <machine> [<project>:]<stage,…>

Let a machine read these stages of a project, in addition to what it has.

access revoke <machine> [<project>][:<stage,…>]

Take a machine's access to a project away, or only some stages.

bash
access grant web-01 myapp:prod,staging
access revoke web-01 myapp:dev

Machines#

Command

What it does

machines [<search>]

List the live machines. --all, --expired or --disabled lists others.

machine add [<name>]

Make a one-time code that enrolls a machine.

machine oidc <name>

Add a machine that signs in with GitHub Actions OIDC. You're asked for its details.

machine approve <machine>

Approve a machine waiting for approval.

machine disable <machine>

Stop a machine's access. It keeps its identity and grants.

machine enable <machine>

Restore a disabled machine's access.

machine rename <machine> <new name>

Rename a machine.

machine revoke <machine>

Remove a machine for good.

invites

List unused one-time codes.

invite show <invite>

Show a code again.

invite revoke <invite>

Cancel a code.

--connection <encrypted|pinned|system> on machine add, invite show and token create chooses how the machine checks the Burrow's connection, as described in CLI. The default is encrypted.

Machine tokens#

Command

What it does

tokens

List reusable machine tokens. --all includes revoked and expired ones.

token create <name>

Create a token that enrolls many machines.

token show <token>

Show a token's enrollment code again.

token revoke <token>

Stop a token enrolling machines.

--grant <project>:<stage,…> sets what its machines may read; repeat it for more projects. A token enrolls machines for 7 days (--expires) and each machine lives 1 hour (--machine-lifetime). --source <cidr>, --hostname <regex> and --name-pattern <regex> limit which machines can enroll, and --description notes what uses it.

bash
token create ci --grant myapp:dev,staging --machine-lifetime 2h

IP allowlist#

Command

What it does

allowlist

The addresses machines may connect from, and whether that's enforced.

allowlist add <address|cidr> [<label>]

Allow an address or range.

allowlist remove <address|cidr>

Remove one.

allowlist enable

Enforce the allowlist.

allowlist disable

Stop enforcing it.

Members and roles#

Command

What it does

members

List the members and invitations.

member invite <email>

Invite someone by email. --role <role> sets their role; you're asked if you leave it out.

member role <member> <role>

Change a member's role.

member disable <member>

Cut a member's access. They keep their role.

member enable <member>

Restore a member's access.

member remove <member>

Remove a member, or withdraw an invitation.

roles

List the roles.

role show <role>

What a role can do.

role create <name> [<capability>…]

Create a role with these capabilities.

role grant <role> <capability>…

Add capabilities to a role.

role revoke <role> <capability>…

Take capabilities away from a role.

role rename <role> <new name>

Rename a role.

role delete <role>

Delete a role. --reassign <role> says where its members move, and is needed when it has any.

sessions

The devices signed in to the Burrow, numbered.

session revoke <#>

Sign a device out. To sign this one out, use logout.

A capability is an area and what may be done there: <area>.read, <area>.write, <area>.delete, or <area>.* for all three. The areas are secret, machine, token, audit, webhook, note, share, member, session, console, burrow_config, display, remote_access, network, security, backup and encryption.

bash
member invite [email protected] --role Developer
role create Deployer secret.read machine.*
role grant Deployer audit.read

Audit log#

Command

What it does

audit

The latest events, newest first.

audit events

The event codes recorded, and how often.

audit actors

Everyone and everything that has done something.

audit export

Save the matching events to a file only you can read. --format csv|json (default csv), --out <file> for where.

audit and audit export take the same filters: --search <text>, --actor <name> (repeat for several), --type <type>, --severity <level>, --event <code>, --ip <address>, --since <24h|7d>, and --from / --to <YYYY-MM-DD>. audit shows 20 events a page; --limit shows up to 100 and --page goes back further.

bash
audit --severity critical --since 24h
audit --event secret.read --actor web-01
audit export --since 30d --format json

Webhooks#

Command

What it does

webhooks

List the webhooks.

webhook events

Every event a webhook can send.

webhook create <name> <url>

Create a webhook. Its signing secret is shown once.

webhook set <webhook>

Change where it sends (--url) or which events (--event, replacing the ones it has).

webhook enable <webhook>

Start sending.

webhook disable <webhook>

Stop sending.

webhook test <webhook>

Send a test event.

webhook secret <webhook>

Show its signing secret.

webhook delete <webhook>

Delete a webhook.

--event takes a code (secret.read), a prefix (machine.*) or *, and can be repeated. --provider chooses how the message is formatted and signed; the default is generic.

bash
webhook create alerts https://hooks.example.com/x --event 'secret.canary.*'

Notes#

Command

What it does

note [<#>]

Show the Burrow's note. 1 is the newest; older ones by number.

note create

Post a new note. Type \n for a line break.

note edit [<#>]

Edit a note.

note delete [<#>]

Delete a note.

Run commands from a script#

ratel -p runs one of the commands above as you and exits:

bash
ratel -p "secrets myapp/prod"
echo -n "$NEW_KEY" | ratel -p "secret set myapp/prod/API_KEY"
ratel -p "project delete old-app" --yes
ratel -p "audit --severity critical --since 24h" --json

A value is read from standard input, --yes answers a confirmation, and --json prints what the Burrow answered. ratel -p help lists the commands. It exits with status 0 when done, 1 when refused or failed, 2 when used wrongly or a confirmation was needed, and 3 when you aren't signed in.

Several Burrows#

You can be signed in to several Burrows at once. ratel login list shows each one and whether its sign-in is still active (--json for scripts). ratel interactive asks which one to open, and --burrow <name> picks one directly:

bash
ratel interactive --burrow my-burrow
ratel -p "secrets myapp/prod" --burrow my-burrow

Sign out#

bash
ratel logout

This ends the sign-in on the Burrow and removes it from this machine; logout inside a session does the same. Add --burrow to pick which one. Ending the CLI's session on the Burrow's Sessions page signs it out too.

Sign-in commands#

Command

What it does

ratel login <burrow-url>

Sign in to a Burrow as yourself, through your browser.

ratel login list

List the Burrows you're signed in to, each checked just now.

ratel interactive

Open a session on a Burrow, signing in first if you need to.

ratel -p "<command>"

Run one session command from a script.

ratel member list

List the Burrow's members and invitations.

ratel whoami

Show the machine identity and who you're signed in as.

ratel logout

Sign out of a Burrow.