bitsreef-cli 0.1.0

CLI tool for BitsReef PaaS platform

BitsReef CLI

bitsreef — deploy and manage BitsReef services from the command line.

Install

# One-liner (installs via pipx, or an isolated venv as fallback):
curl -fsSL https://raw.githubusercontent.com/cygnaragroup/bitsreef/main/cli/install.sh | sh

# ...or with pip / pipx directly:
pipx install bitsreef-cli      # recommended — isolated, on PATH
pip install bitsreef-cli

# ...or from a checkout:
pip install -e 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

Getting started

# Log in to BitsReef (the CLI talks to the hosted BitsReef API)
bitsreef auth login

# Deploy an image to a project in one shot, streaming to completion
bitsreef up --project 4 --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 deployment, and with --follow streams the build/deploy logs and exits non-zero if the deploy fails — so it drops straight into CI.

Linking (stop typing IDs)

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

bitsreef link --project demo --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 demo 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
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 (custom domains)
volumes	list, create, delete
metrics	Current CPU / memory / network snapshot for a service
cron	list, create, trigger, runs, delete (scheduled jobs)
webhooks	list, add, update, remove (project event notifications)
templates	list, info, deploy (service templates)
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 — a token env var (nothing written to disk):
export BITSREEF_TOKEN=<access-token>

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

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

BITSREEF_TOKEN (env) takes precedence over the config file. --json is supported on the read commands (whoami, projects/services list|info, deploy status, env list, functions list|history, logs) and up.

Configuration

Config and JWT tokens live in ~/.bitsreef/config.json (created 0600). The access token is refreshed automatically on expiry. BITSREEF_TOKEN (env) overrides the file when set. The API endpoint is built into the CLI — BitsReef is a hosted service, so there is no server URL to configure.

Development

cd cli
pip install -e . pytest
pytest

Releasing

Publishing is automated by .github/workflows/cli-publish.yml via PyPI trusted publishing (no API token). Bump version in pyproject.toml and bitsreef_cli/__init__.py, then tag:

git tag cli-v0.1.0 && git push origin cli-v0.1.0

The workflow verifies the tag matches the package version, builds the sdist + wheel, twine checks them, and uploads to PyPI. It can also be run manually from the Actions tab (workflow_dispatch).