Skip to main content
The Bota CLI provides terminal workflows for end users, devices, recordings and processing results. It also includes a local MCP server for selected AI assistant tools.
This guide targets the public prerelease @bota.dev/cli@0.2.0-beta.0, from the pinned CLI source. It includes credential status, environment and secure profiles, integration commands, explicit hosted MCP mode and pagination. Matching backend features, native-host qualification and real Platform login require separate verification. Platform webhook management has no public REST route.
Pin the exact version: an unversioned install follows latest, which can select a different cohort. Check the package record, provenance, bota --version and matching --help before use. This source guide is separate from docs-site publication and deployed service acceptance.

Authentication

API-key setup

Inject BOTA_API_KEY through your shell or CI secret manager. Use an explicit environment profile below to pin its API origin and project. On a supported host, this CLI cohort also supports hidden-input OS credential enrollment.
Browser key export is retired in this CLI cohort. Without an explicit developer deployment, bota auth login fails locally; it never exports a project key through a browser callback. Older packages may still implement the retired flow; use API-key setup for current released workflows.
Explicit auth login <key> remains legacy compatibility. It puts the key in command history and plaintext ~/.bota/config.json; prefer secret-manager injection or supported secure profiles.

Platform sessions

The public CLI cohort contains client support for protected enrollment/recovery and shared CLI/MCP developer sessions. It accepts fixed --developer-deployment dev or --developer-deployment prod selections and an explicit --developer-profile <name> for use. Local MCP additionally requires --mode hosted; stdio MCP never prompts or starts login. These selectors do not establish active production enrollment or qualify an installed native/browser flow. Use an existing Platform account with active organization owner/admin access to the chosen project and approve only the needed read scopes. Enrollment is self-service within those existing permissions. Account creation remains separate. The native source path targets Windows x64/local NTFS with Node 22.23.2 or 24.19.0. Uncertain enrollment or refresh retains the named profile for supported inspection/recovery; never repeat code exchange or bypass storage refusal. The historical npm 0.1.0 package does not provide this workflow. After the selected deployment and native host are qualified, choose the browser explicitly when needed:
The CLI emits the same attempt’s authorization URL on stderr only after protected custody acknowledges it. Keep the command running and open the entire URL in a browser on the same computer for its owned loopback callback. Without --no-browser, login opens the operating system’s browser by default. There is no automatic manual fallback after browser-launch failure. Keep the transient URL out of saved logs, issue receipts and shared chat; neither PKCE/recovery verifier, token, authorization code nor password is printed. Consent, PKCE, deadlines and named recovery are unchanged.

Check status

This CLI cohort calls credential identity and shows the verified project, organization, credential ID/type, stored test flag and granted scope metadata. It prints no reusable key, key hint or API URL. Restricted keys do not need end_users:read for this check. Failures distinguish authentication, forbidden access, quarantine, rate limits and unavailable/malformed service responses; they return a nonzero exit and never fall back to reading end users. An old backend’s missing identity endpoint does not establish that a credential is invalid. JSON success goes to stdout; structured failures go to stderr. Without --profile, existing credential selection is preserved: a saved key takes precedence over BOTA_API_KEY. Remove the saved selection explicitly before using an environment key. Restricted-key environment input remains available; native credential storage and delegated Platform login are separate work.

Environment profiles

Inject BOTA_API_KEY through your shell or CI secret manager. Enroll a trusted API origin explicitly, then select the profile for terminal or local MCP work:
Creation verifies project developer identity and stores only the profile name, API origin, project/organization IDs and environment-provider metadata under ~/.bota/profiles/. It saves no key, hint, hash or granted scopes and refuses an existing profile name. Secret and restricted keys, including empty restricted grants, may resolve identity; backend permissions still govern each operation. Selected cloud commands verify the current injected key against the saved project and organization before proceeding. Conflicting --api-url or BOTA_API_URL values refuse before key resolution or a request. Missing or rejected keys never fall back to saved configuration or browser login. Local development HTTP requires a literal loopback address and explicit --allow-http-loopback during enrollment. auth profiles list and remove need no key or network. Removal deletes only local metadata and does not revoke a key or stop an existing MCP process. Both local MCP modes keep one verified startup context; restart after changing environment or metadata. Legacy auth login and logout refuse --profile. This profile mode adds no native secret store, automatic migration, default profile or Platform OAuth. Help and manual webhook forwarding remain credential-free.

Secure API-key profiles

The Windows x64/local NTFS path requires supported Node 22.23.2 or 24.19.0 and successful host admission. Hidden input keeps key bytes out of command arguments:
Keys live in the OS credential store; transactional metadata contains identity, state and exact store references. Runtime, ownership and ancestor-permission checks must pass. Refusal has no plaintext fallback or automatic permission repair. Pending recovery or a conflicting origin stops selection. Each selected action and MCP list/call rereads state and verifies current project/organization identity while holding the namespace lock through cleanup. Removal stops later requests but does not revoke the project key. Explicit BOTA_API_KEY overrides must match the profile’s project/organization; empty or rejected overrides never fall back. Do not combine the two profile selectors. Availability in the public CLI package does not qualify native storage on a particular host or activate delegated Platform login.

Logout

Removes the saved key from ~/.bota/config.json.

Commands

End Users

For end-user connections, see end-user MCP setup. The CLI token commands issue Bota end-user MCP credentials and require a secret project key. They are separate from developer login. Issue output contains a secret; keep it out of assistant context and build logs.

Provider integrations

Manage project-scoped ASR/LLM provider credentials with integrations:read for reads and integrations:write for changes and tests. This public CLI cohort includes the commands below; use a compatible deployed backend and its current provider/admission policy:
Enter keys only through Platform or standard input from your secret-management flow. The CLI accepts no raw provider key argument, does not echo the input, and reports has_error rather than raw provider diagnostics. Tests use the stored key and check basic validity and applicable policy, not the complete processing pipeline or provider approval. See the integration administration guide.

Devices

Recordings

Date bounds apply to recording creation time: --start-date is inclusive and --end-date is exclusive. Filters can be combined with end-user, device, status and cursor selection. Search and processing-status filters are not public recording-list parameters.

Webhooks

Manage webhook endpoints in Platform. bota webhooks list, bota webhooks get and automatic bota listen registration report that management is unavailable through public REST. They do not create a tunnel or send requests to an unmounted /v1/webhooks route.

Manual webhook forwarding

Bring an existing tunnel pointing at http://127.0.0.1:4242, then configure its public destination and subscribed events in Platform. Manual forwarding needs no API key and creates no tunnel or webhook registration. --tunnel-url can record that an existing tunnel is supplied; it is informational. Configure events in Platform rather than using --event. The listener binds to 127.0.0.1, accepts POST bodies up to 1 MiB and forwards once to an HTTP(S) loopback receiver without embedded credentials. Original bytes and Bota signature/timestamp/event-ID headers are preserved so your receiver can verify signatures. Incoming Authorization is not forwarded; redirects are refused. Forwarding has a 10-second deadline and failures return 502. Ctrl+C/SIGTERM closes the listener and cancels in-flight forwards.

Trigger test events

Fire a test webhook event without needing real device activity:
Select the endpoint in Platform and pass its ID explicitly. The command invokes hosted MCP test delivery and reports transport, tool and delivery failures with a nonzero exit status. This sends a test event to the configured destination.

MCP server (stdio)

Use the existing local compatibility tools with the default mode:
Add to Claude Code:
The five integration administration tools forward to hosted MCP with the active project credential. They accept no raw provider keys. Older local tools keep their existing implementation and result shapes; local MCP does not expose every CLI command or provide full hosted parity. Local list_webhooks reports the unavailable REST management boundary. List commands and supported list tools accept cursors to retrieve subsequent pages.

Opt in to hosted tools

This CLI cohort includes a stdio bridge for clients that need local process transport while using the hosted MCP contract:
To register that mode with Claude Code:
Hosted mode uses your configured Bota credential and API origin. A project API key receives the hosted developer tools allowed by its scopes; an end-user token receives the hosted end-user tool set. It introduces no browser login, OAuth exchange or credential issuance. Restart the bridge after changing its selected credential or API origin. Use a compatible backend environment; client package delivery does not establish complete migration or production backend acceptance. The bridge forwards tool-list cursors and complete call results, including structured content and tool-error flags. It does not translate hosted results into legacy shapes: hosted recording details are nested, an external-ID lookup returns one end user, and omitted transcription language defaults to English. Update any automation that expects flattened local recordings, a lookup page, or legacy language behavior before choosing hosted mode. Each list/call reaches the hosted server for fresh authentication and admission; there is no local inventory cache, automatic retry or fallback to legacy tools. The current stateless backend cannot reliably notify a client that the tool list changed. Refresh tools explicitly, or restart the MCP connection after a scope change. A cached client tool list never grants invocation rights. Requests have a total 30-second budget. Cancellation, timeout or shutdown can leave the remote outcome uncertain: closing the bridge does not prove a job, webhook or mutation was cancelled or rolled back. Retain the available request and resource facts, reconcile the result, and decide explicitly whether another action is appropriate. The bridge does not replay the mutation. See the hosted bridge contract.

Global flags

Example: point at a different environment


Output formats

By default the CLI prints human-readable tables. Add --json to get raw JSON for scripting:
Failed requests exit nonzero and report available HTTP status, error code, parameter, request ID and Retry-After information on stderr. The CLI does not automatically replay the request. Recording detail commands and local MCP return a failure when a requested transcription or summary read fails; an empty result list remains a successful response.

Configuration file

Credentials are stored in ~/.bota/config.json:
apiUrl is only written when using a non-default environment. You can also use environment variables instead of the config file: