CLI

The CLI ships with the Python package:

pip install heybee
heybee auth login        # opens your browser; or set HEYBEE_API_KEY

Browser credentials are stored in your operating system keychain and are never printed. heybee auth logout revokes the credential on HeyBee before removing it locally. Browser authorization asks you to choose a workspace. The resulting credential is permanently scoped to that workspace.

Everyday commands

# Inspect the workspace bound to this credential
heybee workspace list
heybee workspace current

# Create and inspect evaluations
heybee evaluation create --file evaluation.json
heybee evaluation show <evaluation-id>
heybee evaluation readiness <evaluation-id>

# Upload a JSON array of samples (local files or inline text)
heybee sample upload <evaluation-id> --file samples.json

# Create a voting link and watch progress
heybee link create <evaluation-id>
heybee evaluation monitor <evaluation-id>

# Read the decision and export the evidence
heybee result show <evaluation-id>
heybee result export <evaluation-id> --output evidence.zip

Add --axis-key <criterion> to result show or result evidence for a single criterion’s decision. heybee huggingface import, list, and status drive dataset imports. Evaluations are created in the workspace bound to the current credential. Use heybee workspace credits <workspace-id>, heybee workspace members <workspace-id>, and heybee workspace invites <workspace-id> to inspect its state. Invitations require confirmation. To use another workspace, run heybee auth login again and select it. Explicit workspace commands are also available for automation:

heybee workspace evaluations <workspace-id>
heybee workspace credit-transactions <workspace-id>
heybee workspace api-key list <workspace-id>
heybee workspace huggingface status <workspace-id>
heybee notification list --scope workspace --workspace-id <workspace-id>

Creating or revoking a key and connecting or disconnecting a workspace integration require confirmation. Add --yes only after the action has been approved.

Scripting

Add --json to any command for stable machine-readable output. Errors include an error code, HTTP status, and request ID. Pass --idempotency-key on writes you might retry, such as link creation or pause and resume, so a rerun never creates a duplicate. The CLI follows the same feature, role, and quota rules as the app, and interactive use always confirms before anything destructive or paid.

Headless machines

Create an API key under Workspace settings → API keys, then set it on the machine:

export HEYBEE_API_KEY="your-api-key"

Build

Reference

Everyday commands

Scripting

Headless machines

​Everyday commands

​Scripting

​Headless machines

Everyday commands

Scripting

Headless machines