CLI

The RatelKey CLI, ratel, enrolls a machine into your Burrow, reads secrets from it, and runs your commands with them. It runs on Linux, macOS and Windows, and prints values in a form that drops straight into shell scripts.

To manage a Burrow from the terminal as yourself, see Interactive CLI.

Install#

npm install -g @ratelkey/cli

npm installs the build for your platform: Linux on x64, arm64 or arm, macOS on Intel or Apple silicon, and Windows on x64 or arm64. To run a single command without installing, use npx @ratelkey/cli <command>.

Update#

ratel update

ratel update installs the latest version through npm. ratel update --check only reports, and exits with status 1 when a newer version exists. If npm's global folder needs administrator rights, or the CLI was installed another way, it prints the command to run instead.

Enroll a machine#

Add the machine on your Burrow's Machines page as described in Command / Ed25519, then run the command it gives you on the machine you are enrolling:

npx @ratelkey/cli machine bootstrap <code>

The machine registers under its hostname unless you pass --name. It generates its own Ed25519 key, sends your Burrow only the public half, and keeps the private key in ~/.burrow/burrows/<burrow>/. The code works once.

Registered web-01 to my-burrow.
Machine  4f9c2a10-7b3e-4d51-9a6c-2e8f10b4d773
Identity /home/you/.burrow/burrows/burrow-a1b2c3d4e5f60718

Enrolling the same machine into the same Burrow again replaces its identity there. The earlier machine stays on the Burrow's Machines page until you remove it. To keep identities somewhere other than ~/.burrow, set BURROW_HOME.

Read a secret#

A secret is addressed as project/environment/NAME. Its value prints alone on standard output, so it goes straight into a variable:

export DATABASE_URL=$(ratel secret get myapp/prod/DATABASE_URL)

A structured secret prints as JSON, so it pipes into jq. Name a field to read just that one:

ratel secret get myapp/prod/STRIPE | jq -r .publishable_key
ratel secret get myapp/prod/STRIPE publishable_key

Set a default environment once and bare names resolve against it. RATEL_ENV overrides it for one command, and a full path always wins.

ratel environment set myapp/prod
ratel secret get DATABASE_URL
RATEL_ENV=myapp/staging ratel secret get DATABASE_URL

ratel secret list prints every secret the machine can read, one path per line, and ratel project list shows each project it can read and its access there. What a machine can read is set from Machine grants.

Run a command with secrets#

ratel run loads every secret in an environment into a command's environment variables, then starts the command:

ratel run --env myapp/prod -- node server.js

Without --env, it uses RATEL_ENV or the default environment. A structured secret sets one variable per field, named after the secret: the host field of DATABASE becomes DATABASE_HOST. The command's exit status is ratel run's exit status. Canaries are never loaded.

To run several commands, pass them as one string:

ratel run --command "./migrate && ./serve"

--only API_KEY,DATABASE loads just those secrets. A variable that is already set takes the Burrow's value; --preserve-env API_KEY keeps its existing value, and --preserve-env true keeps every existing value.

Restart on changes#

With --watch, the command restarts whenever a secret in the environment changes:

ratel run --watch -- node server.js

Read secrets from a file#

With --mount, the secrets are served at a path instead of set as variables, and the command finds the path in RATEL_SECRETS_PATH:

ratel run --mount secrets.json -- ./app

A path ending in .json gets JSON, anything else gets .env lines; --format json or --format env chooses. The path is removed when the command ends. On Linux and macOS nothing is written to disk, and --mount-max-reads <n> stops serving it after n reads.

ratel run needs a Burrow on version 5.1.1 or later.

Several Burrows on one machine#

A machine can be enrolled into more than one Burrow. With one identity, every command uses it. With several, ratel burrow list shows them, and ratel burrow set <name> picks the default. For one command, pass --burrow after the subcommand, or set RATEL_BURROW for the session. A Burrow can be named by its name, the machine id, or its URL.

ratel secret get --burrow my-burrow myapp/prod/DATABASE_URL
ratel whoami --burrow my-burrow

OIDC#

In a GitHub Actions workflow, the CLI authenticates with the token GitHub mints for each run, with no key on the runner:

ratel auth use oidc --burrow https://burrow.example.com --fingerprint <fingerprint>
ratel secret get myapp/prod/DATABASE_URL

Leave out --fingerprint for a Burrow with a publicly-trusted certificate. The audience defaults to the Burrow's address; pass --audience if you registered the machine with another. ratel auth use ed25519 switches back to the machine's key. The job needs permissions: id-token: write.

Connection trust#

Each enrolled machine trusts its Burrow the way you chose under Connection when you added it. ratel tls show lists the setting for each Burrow, and ratel tls set changes it without enrolling again:

Add --burrow to pick which Burrow when there are several. --insecure_tls skips certificate checks for one command, and ratel tls set insecure for every command until ratel tls set secure. Keep those for a network you already trust.

Commands#

When your Burrow refuses a request, the CLI prints the Burrow's own reason on standard error and exits with status 1. A mistyped command exits with status 2. ratel run exits with the status of the command it ran.