Bento Documentation

The CLI builds its command list from the Bento API. Endpoints are grouped by tag, so each one becomes bentolabs <group> <command>.

bentolabs --help                     # list available groups
bentolabs traces --help              # list commands under "traces"
bentolabs traces list --help         # see flags for one command

When a command you expect is missing, bentolabs refresh pulls a fresh command list from the API.

How arguments work

A generated command takes three kinds of input: path params, query params, and a request body. Path params like /things/{thing_id} become required positional arguments, in the same order as the path. The workspace_id path param is the exception. It’s never a positional; the CLI fills it from --workspace or the saved default. Query params become keyword --flags, with types drawn from the API spec (string, int, float, bool, list). Repeat the flag to pass a list. A request body arrives through --data '<json>', --data-file <path>, or stdin.

# Positional path param
bentolabs signals get <signal-id>

# List-valued flag (repeat the flag)
bentolabs traces list --tag prod --tag errors

# Body from a flag
bentolabs <group> <create> --data '{"name":"prod"}'

# Body from a file
bentolabs <group> <create> --data-file ./payload.json

# Body from stdin
cat payload.json | bentolabs <group> <create>

With no workspace set, the CLI prints a hint pointing at bentolabs workspaces list and bentolabs workspaces use <id>.

Shared flags

These flags work on every generated command:

Flag	What it does
`--workspace <id>`	Use this workspace instead of the saved default. Only on commands that need one.
`--data '<json>'`	Send a JSON request body inline.
`--data-file <path>`	Send a JSON request body from a file.
`--output <mode>`	`pretty` (default), `raw`, or `table`. See below.
`--help`	Show the command’s signature and exit.

Output modes

Pretty-printed JSON is the default. Switch with --output:

Mode	Use case
`pretty`	Default. Human-readable JSON with syntax highlighting.
`raw`	Plain JSON to stdout. Pipe into `jq`, `grep`, or a file.
`table`	Renders a table for list endpoints. Falls back to pretty if the shape is not tabular.

Table mode also unwraps the common {"items": [...], "next_cursor": ...} shape, so list endpoints render directly.

bentolabs traces list --output table
bentolabs traces list --output raw | jq '.items[] | .id'

Built-in commands

A small set of commands are hand-written rather than generated.

`auth`

bentolabs auth login          # opens the browser, saves tokens to the keychain
bentolabs auth whoami         # show signed-in identity and current workspace
bentolabs auth logout         # revoke the session and clear local tokens

Tokens refresh automatically near expiry. If a refresh fails, say because another process already rotated it, the next command returns a clean 401 and asks for bentolabs auth login again.

`workspaces use`

Save a default workspace so other commands don’t need --workspace.

bentolabs workspaces list
bentolabs workspaces use <ws-id>

The flag wins over the saved default when both are present.

`raw`

Send a raw request to any API path, for endpoints the generated tree doesn’t expose cleanly.

bentolabs raw GET /health
bentolabs raw GET /v1/workspaces/<ws-id>/traces
bentolabs raw POST /v1/workspaces/<ws-id>/some-endpoint --data '{"x":1}'

raw uses the same auth and --output modes as generated commands. It passes path params through untouched, including workspace_id. The body comes from --data or --data-file only, not from stdin.

`refresh`

Pull a fresh copy of the command list from the API. Run this when an endpoint is missing from --help.

bentolabs refresh

The output reports how many operations were cached.

`config`

Inspect the active CLI configuration.

bentolabs config show

config show prints the current values and the path to the config file on disk. auth login writes the tokens, and workspaces use writes the default workspace. The config file is created with 0600 permissions.

`version`

Print the installed CLI version.

bentolabs version

Examples

List the 5 most recent traces in the default workspace:

bentolabs traces list --limit 5 --output table

Pipe trace IDs into another command:

bentolabs traces list --output raw \
  | jq -r '.items[].id' \
  | head -20

Call an endpoint that isn’t in the cached command tree yet:

bentolabs refresh
bentolabs <new-group> --help

Send a request that the generated tree doesn’t cover:

bentolabs raw GET /v1/workspaces/<ws-id>/new-endpoint

Installation

Install the CLI and sign in.

Python SDK

Send traces and signals from your code.

Get started

Resources

Workspace & sources

Commands

How arguments work

Shared flags

Output modes

Built-in commands

`auth`

`workspaces use`

`raw`

`refresh`

`config`

`version`

Examples

See also

Installation

Python SDK

​How arguments work

​Shared flags

​Output modes

​Built-in commands

​auth

​workspaces use

​raw

​refresh

​config

​version

​Examples

​See also

Installation

Python SDK

How arguments work

Shared flags

Output modes

Built-in commands

`auth`

`workspaces use`

`raw`

`refresh`

`config`

`version`

Examples

See also