CLI reference

bitsreef deploys and manages BitsReef services from your terminal — and drops cleanly into CI and scripts.

Install

pipx install bitsreef-cli    # recommended — isolated, on PATH
pip install bitsreef-cli

Shell completion

eval "$(bitsreef completion bash)"   # add to ~/.bashrc
eval "$(bitsreef completion zsh)"    # add to ~/.zshrc
bitsreef completion fish > ~/.config/fish/completions/bitsreef.fish

Log in

bitsreef auth login --url https://v1.api.prod.bitsreef.com/v1

Tokens are stored in ~/.bitsreef/config.json (created 0600) and refreshed automatically on expiry. bitsreef auth set-url <url> changes the API base URL.

Deploy in one shot

bitsreef up --project my-project --name web --image nginx:latest --port 80 --follow

bitsreef up creates the service if it doesn’t exist (or updates its image if it does), triggers a deploy, and with --follow streams the build/deploy logs and exits non-zero if the deploy fails — so it drops straight into CI.

Linking

Bind a directory to a project/service once, then omit IDs everywhere:

bitsreef link --project my-project --service web   # writes ./.bitsreef.json
bitsreef logs                                      # → the linked service's logs
bitsreef up -i nginx:1.27 --follow                 # redeploy the linked service
bitsreef deploy status                             # linked project's deployments
bitsreef link --show                               # what's linked here
bitsreef unlink                                    # remove the link

The link file (.bitsreef.json) is discovered by walking up from the current directory, like .git. Names or slugs work in place of numeric IDs everywhere (bitsreef logs my-project web), and a default org is remembered after the first pick so multi-org accounts stop re-prompting.

Commands

Command	Purpose
`up`	Create-or-update a service from an image and deploy it (`--follow`, `--json`)
`exec`	Open an interactive shell (`/bin/sh`) in a running container
`link` / `unlink`	Bind this directory to a project/service (`--show`)
`auth`	`login`, `logout`, `whoami`, `set-url`
`projects`	`list`, `info`, `create`
`services`	`list`, `info`, `restart`, `stop`, `scale`
`deploy`	`up` (`--follow`), `rebuild`, `status`, `rollback`
`env`	`list`, `set`, `delete`, `reveal`
`domains`	`list`, `add`, `remove`, `verify`
`volumes`	`list`, `create`, `delete`
`metrics`	Current CPU / memory / network snapshot for a service
`cron`	`list`, `create`, `trigger`, `runs`, `delete`
`webhooks`	`list`, `add`, `update`, `remove`
`templates`	`list`, `info`, `deploy`
`functions`	`list`, `create`, `invoke`, `history`, `update`, `delete`
`logs`	View service logs (`--tail`, `--follow` for a live tail)
`completion`	Print a shell-completion script (`bash`, `zsh`, `fish`)

Run bitsreef <command> --help for full options.

CI, scripting & agents

Everything works non-interactively and can emit JSON:

# Auth without a prompt — env vars (nothing written to disk):
export BITSREEF_API_URL=https://v1.api.prod.bitsreef.com/v1
export BITSREEF_TOKEN=<access-token>

# ...or a piped password / a stored token:
echo "$PASS" | bitsreef auth login -u ci --password-stdin --url "$BITSREEF_API_URL"
bitsreef auth login --token "$BITSREEF_TOKEN" --url "$BITSREEF_API_URL"

# Machine-readable output (place --json before the command):
bitsreef --json services list my-project | jq '.[].name'
bitsreef up -p my-project -n web -i img:tag --follow --json   # non-zero exit on deploy failure

BITSREEF_API_URL and BITSREEF_TOKEN (env) take precedence over the config file. --json is supported on the read commands and on up.

Configuration

Config and JWT tokens live in ~/.bitsreef/config.json (created 0600). Env vars (BITSREEF_API_URL, BITSREEF_TOKEN) override the file when set.