Metadata-Version: 2.4
Name: bitsreef-cli
Version: 0.1.0
Summary: CLI tool for BitsReef PaaS platform
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.25
Requires-Dist: rich>=13.0
Requires-Dist: websocket-client>=1.6

# BitsReef CLI

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

## Install

```bash
# 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

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

## Getting started

```bash
# 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:

```bash
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:

```bash
# 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

```bash
cd cli
pip install -e . pytest
pytest
```

### Releasing

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

```bash
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 check`s them, and uploads to PyPI. It can also be run manually
from the Actions tab (`workflow_dispatch`).
