briven
sign up
menu

cli

databases, branches and credentials from a terminal. it is a thin wrapper over the management api with two opinions: your key never appears in an argument, and a connection string never lands in your scrollback by accident.

it is not on npm

There is no published npm package for this tool, so do not install one under the name briven — whatever you would get is not ours. The tool itself is real and it works; today you run it out of the repository with node cli/briven.ts. When it is published, this page will say so.

Every example below is written the long way for that reason. If you have the repository, an alias makes the rest of this page read the way it eventually will.

bash

alias briven='node cli/briven.ts'

export BRIVEN_API_KEY=brk_...
node cli/briven.ts databases list

where your key lives

Two places, in this order. The BRIVEN_API_KEY environment variable wins if it is set, which is the recommended way in CI — the key comes from your secret store, is never written to disk, and disappears with the job. Otherwise the tool reads ~/.config/briven/config.json, a file containing { "apiKey": "..." } and nothing else, written with mode 0600 inside a directory with mode 0700 — readable by you and by nobody else on the machine. XDG_CONFIG_HOME is honoured first, then HOME.

login makes a real request with the key before it saves anything, so a mistyped key is never written to disk — you find out immediately instead of at the next command. And the key is never printed back to you afterwards: not by login, not masked, not in --json. The tool can use your key; it cannot show it to you.

The base URL is https://briven.tech, and BRIVEN_API_URL overrides it if you are pointing at something else.

every command

  • briven loginAsks for an API key, checks it against the API, and only then writes it to disk.
  • briven logoutForgets the stored key.
  • briven databases listEvery database in the organisation.
  • briven databases create <name>Makes one. 1 to 40 characters.
  • briven databases delete <id>Deletes one. There is no second delete — see the management api page.
  • briven databases url <id>Prints the connection string. Guarded — see below.
  • briven databases rotate <id>Issues a new password, drops every open connection, prints the new string. Guarded.
  • briven branches list <database-id>Every branch taken from that database.
  • briven branches create <database-id> <name>Takes a branch.
  • briven helpThe same list, from the terminal.

bash

node cli/briven.ts databases create notes
node cli/briven.ts branches create db_id pr-421 --json

the three flags

  • --jsonPrint the API’s response as JSON instead of a human-readable summary. This is the flag your scripts want.
  • --revealPermit a secret to be printed to a terminal. Only meaningful on the two commands that produce one.
  • --help, -hWhat this command does and what it takes.

That is the complete list, and parsing is strict: an unknown flag is a hard error, not a warning that scrolls past. A typo in a flag on a command that deletes something should stop the command, not be ignored by it.

There is deliberately no --api-key flag. A key passed as an argument is written into your shell history and is visible to every other user on the machine in the output of ps for as long as the command runs. Neither of those is fixable by being careful, so the flag does not exist. Use the environment variable or briven login.

the guard on connection strings

databases url and databases rotate both produce a credential, and both refuse to print it when their output is a terminal unless you pass --reveal. Piping or redirecting always works without the flag, because output that is going into a file or another program is not going into your scrollback, your screen share or your recorded session.

When it does print, the connection string is alone on stdout with no label and nothing around it, and every word of commentary goes to stderr instead. That is what makes the second line below safe: the variable holds the string and only the string.

bash

node cli/briven.ts databases url db_id >> .env
URL=$(node cli/briven.ts databases url db_id)
node cli/briven.ts databases rotate db_id --reveal

exit codes

The exit code is the part of a CLI that scripts actually read, so these are specific rather than the usual zero-or-one. They let a deploy script tell “retry this” apart from “stop and tell a human” without parsing any output.

  • 0It worked.
  • 1You asked for something that is not a command, or there is no key to use.
  • 2The key was refused — the API answered 401 or 403. Wrong key, or the wrong kind of key.
  • 3The request was refused — 400, 402, 404 or 409. The key is fine; what you asked for is not.
  • 4Rate limited. The API answered 429. Wait and retry.
  • 5Something broke at our end — a 5xx, or a bug in the CLI itself.
  • 6It never got there. DNS, TLS or the connection failed, so nothing happened and a retry is safe.

The useful split is 2 against 3: a 2 means the credential is wrong and every retry will fail the same way, while a 3 means the credential is fine and the request was not. A 4 or a 6 is worth retrying; a 1, 2, 3 or 5 is not.

the same gate applies

The CLI is the management API with a nicer face, so it inherits the management API’s rules exactly: you need an organisation-wide key, it must not be read-only, and the management_api feature flag has to be switched on in the dashboard by a human. If the CLI keeps exiting with a 2, that is what it is telling you — read the three gates.

where to go next

Every response shape the CLI prints with --json is documented on the management api page. Once you have a database, run statements against it with sql over http or take the connection string into psql, Prisma or Drizzle — connecting covers that. And branching explains what branches create is actually giving you.