Metadata-Version: 2.4
Name: bentolabs-cli
Version: 0.1.2
Summary: Command-line interface for the Bentolabs platform API
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.0
Requires-Dist: keyring>=24.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
```

## Sign in

```sh
bentolabs auth login
```

Opens your browser to a Bento-branded **Allow / Deny** page. If you're already
signed in to the web app, just click **Allow** and the CLI gets signed in as
you. Your tokens are stored in the OS keychain (macOS Keychain / Linux Secret
Service / Windows Credential Locker), with a `chmod 0600` file fallback for
headless Linux boxes that don't ship secret-service.

```sh
bentolabs auth whoami   # show signed-in identity + current workspace
bentolabs auth logout   # revoke session + clear keychain
```

## Pointing the CLI at a different environment

The CLI defaults to `https://api.bentolabs.ai`. To target a local stack or a
custom deployment, change the API base — three ways, highest priority first:

```sh
# 1. Per-command flag (no persistence) — flag attaches to the subcommand
bentolabs auth login --api-base http://localhost:8080
bentolabs traces list --api-base http://localhost:8080

# 2. Environment variable (per shell)
export BENTOLABS_API_BASE=http://localhost:8080
bentolabs auth login

# 3. Persisted in config (default for every future command)
bentolabs config set api-base http://localhost:8080
```

`bentolabs config show` prints the OS-specific config path plus the
effective values.

### How the browser-side URL is chosen

`bentolabs auth login` needs to open a browser at the matching web app.
The CLI derives this **automatically from the effective `api_base`** —
it never reads a saved value, so switching `api_base` always switches
the web app too. The mapping is:

| `api_base` you set | Browser opens at |
|---|---|
| `http://localhost:8080` or `http://127.0.0.1:8080` | `http://localhost:3000` |
| `https://api.bentolabs.ai` | `https://platform.bentolabs.ai` |
| `https://api-staging.bentolabs.ai` | `https://platform-staging.bentolabs.ai` |
| anything else | the `api_base` itself (you probably want to override) |

If your deployment doesn't follow the `api.* ↔ app.*` convention, force
the web URL explicitly:

```sh
export BENTOLABS_WEB_BASE=https://internal.example.com
bentolabs auth login
```

`BENTOLABS_WEB_BASE` always wins.

## Pick a default workspace

The CLI commands act on one workspace at a time. Set the default once and you
won't need to pass `--workspace` on every command:

```sh
bentolabs workspaces list           # see the workspaces you belong to
bentolabs workspaces use <id>       # persist this as the default
```

To override per command:

```sh
bentolabs traces list --workspace <other-id>
```

The `--workspace <id>` flag wins over the persisted default.

## Usage

```sh
bentolabs --help                           # discovered command groups
bentolabs traces --help                    # ops under "traces"
bentolabs traces list --limit 5            # uses the persisted workspace
bentolabs traces list --tag prod --tag errors
bentolabs raw GET /health                  # ad-hoc escape hatch
bentolabs refresh                          # pull latest command metadata
```

## 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.

## Workspace API keys (for SDKs and CI)

Workspace-scoped API keys still exist for **SDK integrations and CI** — they
just aren't how the CLI itself authenticates anymore. Mint and manage them with:

```sh
bentolabs api-keys create
bentolabs api-keys list
bentolabs api-keys revoke <id>
```

The resulting `bl_pk_…` keys are intended for the SDK or other server-side
callers — not for the CLI. The CLI authenticates only as a human via
`bentolabs auth login`.

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