Metadata-Version: 2.4
Name: bentolabs-cli
Version: 0.1.1
Summary: Command-line interface for the Bentolabs platform API
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# bentolabs-cli

Command-line tools for working with the Bentolabs platform API.

## Install

```sh
uv tool install bentolabs-cli
```

Or with pip:

```sh
python3 -m pip install --user bentolabs-cli
```

For local development from this repo:

```sh
pip install -e apps/cli
```

## Setup

```sh
bentolabs config set api-key bl_pk_...           # from POST /workspaces/{id}/api-keys
```

The CLI uses `https://api.bentolabs.ai` by default, so `api-base` only needs to
be set for local development or a custom deployment:

```sh
bentolabs config set api-base http://localhost:8080
```

Config lives at the OS-specific user config path reported by
`bentolabs config show`. You can also pass `--api-key` per call, or set
`BENTOLABS_API_BASE` / `BENTOLABS_API_KEY` env vars.

Commands are bootstrapped automatically on first use. Run `bentolabs refresh`
when you want to pull the latest API commands.

## Usage

```sh
bentolabs --help                           # discovered command groups
bentolabs traces --help                    # ops under "traces"
bentolabs traces list <ws-id>              # path params positional
bentolabs traces list <ws-id> --limit 5    # query params as flags
bentolabs traces list <ws-id> --tag prod --tag errors
bentolabs raw GET /health                  # ad-hoc escape hatch
bentolabs refresh                          # pull latest command metadata
```

## Auth coverage

The API has two auth systems: Supabase JWT (browser) and API keys (workspace-
scoped, `bl_pk_…` prefix). This CLI authenticates with API keys.

API keys are deliberately treated as **member-level** access — never owner.
That means three tiers:

**Tier 1 — API key works** (`require_workspace_member`, no `get_current_user`):

- analytics, clusters, drift, trajectories, workspace-extraction-config (read)
- traces list, signals list, notification-channels list

**Tier 2 — JWT-only (management/owner-gated)**: API keys 401/404 here on
purpose to prevent privilege escalation:

- workspaces list/rename/users, api-keys list/create, workspace-extraction-config put
- credentials create/update/delete (workspace bearer secrets)
- notification-channels create/update/delete
- sync settings update / workspace reports

**Tier 3 — JWT-only (user identity required)**: routes that resolve access from
Supabase user membership, or write FK columns to `public.users` for audit trails:

- traces get/body/spans/issues by bare trace id
- signals get/events by bare signal id
- notification-channels get/last-delivery by bare channel id
- issues — status changes, comments, updates
- incidents — acknowledge / assign / resolve
- credentials, sync, deep-search mutations
- agent — interactive surfaces

Hitting a JWT-only route with an API key returns 401 (missing user identity)
or 404 (owner gate). The error envelope tells you which.

## Output

JSON by default (pretty-printed via `rich`). Use `--output raw` for unformatted
stdout (pipeable), or `--output table` for list endpoints with simple row
shapes.

## Publish

```sh
just publish-cli
```

The recipe runs the CLI lint/test/build checks, builds the wheel/sdist, then
publishes `bentolabs-cli` to PyPI with `UV_PUBLISH_TOKEN` or `PYPI_TOKEN`.
