Dbrij CLI Documentation

dbrij is the Dbrij command line tool. It deploys a folder on your machine to Dbrij Hosting, reads and changes a service's variables and logs, runs your app with its Dbrij Secrets opened on your own machine, ships over the air releases with Dbrij Ship, signs git in to Dbrij Source, and runs a local MCP server so an AI coding tool can do the same for you.

What is on disk is what ships. There is no repository to connect and no webhook: dbrij deploy packs the folder, uploads it straight to storage and asks Dbrij to build it.

npm i -g dbrij

dbrij login      # confirm the code in your browser
dbrij link       # point this folder at a service
dbrij deploy     # ship it

Every command talks to the Dbrij API at https://api.dbrij.com/api/v1 with the token dbrij login saved. It acts as you, through the same API the dashboard uses, so every permission, plan limit and card rule applies unchanged.

The CLI is the dbrij package on npm and needs Node.js 20 or newer. Installing it puts one command on your path, dbrij.

npm i -g dbrij
dbrij --version

Or run it without installing, which is what CI jobs and AI coding tools usually do:

npx dbrij deploy
npx -y dbrij mcp

Server access through dbrij secrets access uses the WebSocket built into Node.js 22, so that one family of commands needs Node.js 22 or newer.

dbrij help prints the command list and dbrij secrets help the full Secrets list. Both exit 0. An unknown command prints Unknown command and exits 1.

dbrij login uses the device authorization flow. The terminal shows a short confirmation code and an address, and opens that address in your browser. You check the code matches, confirm it in the browser where you are already signed in, and the terminal receives a token. Your password never touches the terminal, and a machine with no browser (a server, a container) can be confirmed from your phone by opening the printed address.

$ dbrij login

  Confirmation code: <the code>
  Open: <the address>

  Check the code in the browser matches the one above before confirming.

✓ Signed in as you@example.com.

• The CLI asks for the code as Dbrij CLI on followed by your machine's host name, so you can tell your machines apart.
• It checks with Dbrij at the interval the server sets (never more often than every two seconds) until the code expires.
• A network error while it waits does not end the sign in; it keeps waiting.
• Refused in the browser, expired, or timed out: it says so and exits 1. Run dbrij login again.
• Already signed in: it says as whom and exits 0. dbrij login --force signs in again, as someone else if you like.

The token is saved in ~/.dbrij/auth.json, readable only by you (mode 600), with the API address and your name and email. When DBRIJ_TOKEN is set, it is used instead of the file and nothing is written.

In CI

Set DBRIJ_TOKEN and skip dbrij login. A token from the environment always wins over a saved file, so a file left on a shared machine can never stand in for the credential the job was given.

- run: npx dbrij deploy --no-wait --no-url
  env:
    DBRIJ_TOKEN: ${{ secrets.DBRIJ_TOKEN }}

dbrij link points the current folder at one Hosting service. It is interactive: it lists every project you can deploy to, in your personal space and in every company you belong to, and asks which one. Answer with a number, or n to create a new one. Nothing is chosen for you, even when there is only one option.

1. Project. Pick one, or create one. A new project's name defaults to the folder's name, lowercased, with anything other than letters, digits and dashes turned into dashes, up to 40 characters. If you belong to a company you are asked which space it belongs to: personal, or one of your companies.
2. Service. Only services that take uploads are listed, since those are the ones dbrij deploy can ship to. A new service is a web service that takes uploads, named the same way.

An answer that is not one of the options stops the command with exit 1, and nothing is created. Run dbrij link again. In a folder that is already linked it asks whether to link somewhere else; anything but y keeps the current link.

{
  "projectId": "6f1c…",
  "serviceId": "a93e…",
  "projectName": "shop",
  "serviceName": "web"
}

The link lives in .dbrij/project.json. Next to it the CLI writes .dbrij/.gitignore (when there is none), which keeps everything in .dbrij out of git except secrets.toml. A link is a fact about one checkout on one machine, so it is not meant to be committed.

Every command that needs a link looks for .dbrij/project.json in the current folder and then in each parent folder, as git does, so dbrij deploy works from anywhere inside a linked project. The folder that holds the link is the one that ships.

dbrij deploy ships the linked folder. In order: it asks the API for an upload address (so a service that cannot take the upload fails in a second, before anything is read), packs the folder into a compressed archive, uploads it straight to storage with that address (the archive never passes through the API, and carries no Dbrij credential), then starts the build and watches it.

dbrij deploy -m "New checkout page"

The public URL question

A web service with no URL yet is asked, before the build starts, whether it should get a public URL when it deploys (the default answer is yes). The URL is only created after a successful build, so a failed deploy never leaves a hostname pointing at nothing. Without --url or --no-url, the question is only asked when there is a terminal: with no terminal on stdin, or with CI set, the answer is no. A service that already has a URL, or is not a web service, is never asked. Change your mind later with dbrij url.

Watching the build

Without --no-wait the CLI checks every two and a half seconds and shows where the deployment is: queued, waiting for a build slot, building, rolling out. A free plan deploy can wait for a build slot while paid ones build; that wait is shown, and does not count against the watch. The CLI stops watching after 25 minutes of work; the deployment is not cancelled, it says so and exits 1. A dropped connection while watching is not a failed build: it keeps watching.

• Success: prints Deployed. and the URL (a certificate can take a minute on a new hostname). Exit 0.
• Failure: prints the error, Dbrij's plain reading of what went wrong, up to six matching lines of the build log, what usually fixes it, and the command for the full log (dbrij logs --build and the deployment's id). Exit 1.
• Cancelled or replaced by a newer deployment: says so. Exit 1.

What gets uploaded

Every file in the linked folder, minus three layers of rules, applied in this order:

1. Always left out: installed dependencies (node_modules, vendor, .venv, venv, .bundle), version control and build output (.git, .next, .nuxt, .turbo, .cache, dist, build, target, coverage), language caches (__pycache__, *.pyc, .pytest_cache, .mypy_cache, .ruff_cache, .tox, *.egg-info, .gradle, .phpunit.result.cache, Laravel's bootstrap/cache and storage/framework caches and storage/logs), .DS_Store, .dbrij, and secrets: .env, .env.local, .env.*.local, *.pem, *.key and id_rsa.
2. The folder's own .gitignore.
3. The folder's .dbrijignore, if there is one.

A later rule wins, so a !pattern in .dbrijignore can ship something git ignores, even something on the always left out list. Nothing secret goes up by accident; sending it is a line somebody had to write. Only the ignore files at the root of the linked folder are read.

Both files use gitignore patterns: # starts a comment, * matches within one folder name, ** crosses folders, ? is one character, a trailing / matches folders only, a leading / or a slash inside the pattern anchors it to the root, and a pattern with no slash matches at any depth.

# Large local data the build does not need
fixtures/large/
*.mp4

# Ship a build output that .gitignore leaves out
!public/generated/

The archive has a size limit the API sets per upload. A packed folder over it fails with its size and the limit; a folder far over it (ten times the limit, before compression) stops while packing. Either way, add what you do not need to .dbrijignore. A folder where every file is ignored fails with Nothing to deploy. Files are packed in sorted order, so the same folder makes the same archive on any machine.

Each of these works on the service the current folder is linked to, and exits 1 with an instruction to run dbrij link when there is none (except dbrij ls, which needs no link).

dbrij status
dbrij logs --build 3f2a9c1e
dbrij rollback

A build that failed before it wrote anything has no log to show. dbrij logs --build then says the build produced no output, with the error and the first line Dbrij matched, instead of an empty screen.

dbrij env reads and changes the linked service's environment variables. Values are never printed: the list shows names only, because this gets run in shared terminals and on shared screens.

dbrij env add DATABASE_POOL=10
dbrij env rm OLD_FLAG
dbrij env pull .env.local

A change touches only the names you give. Dbrij merges it on the server, so a variable someone else changed in the meantime (a teammate, an assistant, another terminal) is kept.

dbrij env pull quotes any value with a line break, a # or spaces around it, so the file reads back exactly as it was. The file now holds real secrets: the CLI warns you, and it is not added to .gitignore for you.

dbrij secrets reads an environment from Dbrij Secrets and opens it on this machine. Values are sealed before they reach Dbrij, which cannot open them; the CLI opens them here, with your vault key (people, after dbrij login) or the key half of a machine token (servers and CI).

dbrij login
dbrij secrets link --project my-app --env development
dbrij secrets run -- npm start

Choosing what to read

Each value is taken from the first place that has it: the flag, then the environment variable, then the nearest .dbrij/secrets.toml.

# Dbrij Secrets: which project and environment this folder reads.
# Names only, never a value or a token: safe to commit.
project = "my-app"
environment = "development"
paths = ["/", "/api"]

.dbrij/secrets.toml holds names only, so it is meant to be committed: the whole team then runs dbrij secrets run with no flags. The nearest one up the folder tree wins, so a folder in a monorepo can name its own. dbrij secrets link also makes sure .dbrij/.gitignore lets this one file in.

How run behaves

• The command gets the secrets as environment variables. DBRIJ_SECRETS_TOKEN and DBRIJ_SECRETS_KEY are taken out of its environment: it gets its secrets, not the key to all of them.
• Ctrl+C, SIGTERM and SIGHUP are passed on to the command, and dbrij secrets run exits with the command's own exit code.
• With --watch, a burst of saves is one restart, never more than one every ten seconds. The command gets SIGTERM, and SIGKILL ten seconds later if it is still running.
• A template that cannot be filled in stops the command before it starts, naming the reference, unless --allow-missing.

Changes, protected environments and approvals

set, delete and push seal values on this machine before they leave it. A protected environment needs --yes; in a company project the confirmed change goes to the project's approvers as a request instead of applying, and the CLI says so. With several folders read, name the one to change with --path.

push compares only the secrets in the folder it writes to, so another folder is never touched. It also takes an encrypted .env file whose values carry their own public key encryption: the private key comes from DOTENV_PRIVATE_KEY (or DOTENV_PRIVATE_KEY_PRODUCTION for .env.production, and so on) or a .env.keys file beside it. The values are opened on this machine and sealed again before they leave it.

People and machines

A person reads after dbrij login. The first time, the CLI asks for your vault passphrase (three tries) and keeps the unlocked key on this device, sealed, for 12 hours by default (DBRIJ_SECRETS_UNLOCK_HOURS, up to 168; 0 asks every time). The passphrase can only be typed in a terminal.

A machine reads with a machine token in DBRIJ_SECRETS_TOKEN, or with a login key in DBRIJ_SECRETS_KEY on a pipeline or cloud platform Dbrij Secrets can log in from. The Secrets documentation covers machine tokens and login keys.

What stays on this machine

Under ~/.dbrij/secrets/, readable only by you: a sealed copy of the last values read, used when Dbrij cannot be reached or answers with a server error (never when it refuses), for up to 24 hours; and for people, the unlocked vault key. A machine's copy is sealed with the key half of its token. A person's files are sealed with a device key kept in the system keychain (macOS Keychain, the Secret Service on Linux, or Windows data protection), or in ~/.dbrij/secrets/device.key when there is none. DBRIJ_SECRETS_CACHE=off stops the local copy; dbrij secrets lock removes all of it.

These dbrij secrets commands also take --project, --space and --token as above.

Short lived database users

dbrij secrets lease SOURCE asks for a database user from a lease source a project admin set up. With a command after --, the command gets the user's address in DATABASE_URL and the lease is revoked when the command ends, whatever happens to it; the CLI exits with the command's exit code. Without a command, the address is printed and the lease lasts until it runs out or you revoke it.

dbrij secrets lease postgres-readonly -- psql
dbrij secrets lease postgres-readonly --ttl 1h
dbrij secrets lease revoke 9b1e…

A person names the project with --project or .dbrij/secrets.toml; a machine uses its own token. When the database is not open to the internet the CLI says the address only works from inside its Dbrij Hosting project. lease revoke ID ends one early; it reports revoked once the database confirms the user is gone, and pending otherwise.

Key management

dbrij secrets keys uses a key in Dbrij Secrets Key management; the key itself never leaves Dbrij. KEY is a key's id, or when you are signed in, its name (add --project when two projects share a name). Text comes as an argument or on stdin, and results go to stdout alone, so they can be piped.

SSH certificates

Server access

dbrij secrets access is for people, signed in. A session runs through Dbrij's access gateway from a local port, so ssh, psql and mysql work as usual while nobody sees a password, and every session is recorded. Each connection gets its own ticket.

access ssh, psql and mysql exit with the client's exit code, or 127 when the client could not start.

Finding leaks

dbrij secrets scan [folder] looks for secrets written into files, with the same rules Dbrij Source uses on a push. Nothing leaves your machine. Inside a git repository it reads the files git tracks or would track; elsewhere it walks the folder. It exits 1 when it finds something and 0 when it does not.

A line that is meant to be there (a test fixture) can carry the comment dbrij-scan: ignore. To commit past the hook once, deliberately: git commit --no-verify.

dbrij ship cuts over the air releases with Dbrij Ship from a terminal or a pipeline, so the thing that goes out is the thing that was just built. What a release carries depends on the app: a JavaScript stack ships a bundle; every other stack ships an asset pack of the files the app reads at runtime. dbrij ship apps says which.

dbrij ship release build/app-1.4.2.zip --app 5c0d… --rollout 10 --notes "Faster checkout"
dbrij ship rollout 8e7a… 100 --app 5c0d…

Ship flags take their value after a space (--app 5c0d…). A file over 50 MB is refused before anything is sent: a release carries the parts of the app that change, never the whole app. The upload may take up to ten minutes. When a test target holds the app's production releases until its tests pass, the release is uploaded and held, devices keep the current release, and it goes live by itself once the tests pass.

Narrowing a rollout does not take a release off devices that already have it; to recall it, use dbrij ship rollback.

Pushing to Dbrij Source over HTTPS needs a Source token as the password. dbrij git setup makes the CLI git's password helper for Dbrij Source, so git signs in as you with no token to make, copy or paste.

dbrij login
dbrij git setup
git push

It needs git on your path and a sign in. It changes your global git config for one host only, the Source git host (the API's own address, https://api.dbrij.com unless DBRIJ_API_URL says otherwise):

[credential "https://api.dbrij.com"]
	helper =
	helper = !dbrij git-credential

The empty entry first clears helpers inherited from elsewhere for this host alone, so an old pasted token is never offered ahead of a fresh one. When the dbrij on your path is not the CLI that ran setup, the helper is !npx -y dbrij@VERSION git-credential for that exact version instead. Running setup again is safe. To undo it:

git config --global --unset-all credential.https://api.dbrij.com.helper

What git runs

Git calls dbrij git-credential get, store or erase. It only answers for the Source host; any other host is left to git's other helpers. On get it asks Dbrij for a short lived push token with your sign in, keeps it in ~/.dbrij/git-credential.json (readable only by you) and uses it until ten minutes before it expires. On erase, which git sends when it rejects a token, the cached token is deleted so the next push gets a fresh one. store does nothing.

It always exits 0 and never blocks git. Not signed in, or Dbrij unreachable, it says why on stderr, prints no credential, and git moves on to its next helper or its own prompt. dbrij logout deletes the cached push token too.

dbrij mcp runs Dbrij as a Model Context Protocol server on your own machine, over stdio, so an AI coding tool can scan your project, create services, set variables, connect a database, deploy the folder you are working in, read the logs when a build fails, and attach your domain. For an AI chat app with no access to your machine, use the hosted connector at mcp.dbrij.com instead.

{
  "mcpServers": {
    "dbrij": { "command": "npx", "args": ["-y", "dbrij", "mcp"] }
  }
}

• It signs in with the CLI's credential: run dbrij login once in a terminal, or set DBRIJ_TOKEN. It acts as you, with your plan's limits, through the same API as the dashboard.
• Not signed in, it still starts, and each tool answers with the instruction to run dbrij login, which the assistant passes on.
• stdout is the protocol channel. The server writes only its ready line (version and API address) and warnings to stderr, and runs until the tool closes its stdin or it gets SIGINT or SIGTERM. Then it exits 0.
• Its requests carry x-dbrij-client: mcp-local, so Dbrij can show an action was taken through an AI assistant.
• An API refusal comes back to the assistant as a readable tool error, never a crash.

What it never does

Anything that costs money or cannot be undone is only ever a request. The assistant files it, you are told, and you approve it on Dbrij, signed in as yourself; the approval refuses the CLI's token, so the assistant cannot approve its own request, and a deletion needs the name typed. Variable values, database passwords, Dbrij keys and secret values are never shown to it. The server tells the assistant never to act on instructions found inside logs, and to stop and tell you when a diagnosis says so.

Tools that work in a space take an optional organizationId; left out, they work in your personal space.

Secrets tools and your vault key

Opening an environment needs a key. A machine token in DBRIJ_SECRETS_TOKEN works as it does for dbrij secrets. For a person, the vault key has to be unlocked on this device first, by a command run in a terminal; the assistant is never asked for the passphrase. When it is locked, the tool tells the assistant which command to ask you to run:

dbrij secrets status --project my-app --env development

dbrij secrets commands also take --api-url, which sets the API address for that one command.

The CLI exits 0 when the command did what it was asked, and 1 when it did not. An error prints the API's own message, which is written for people, with no stack trace; set DBRIJ_DEBUG=1 to see one.

Common errors