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.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
InjectBOTA_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.
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:
--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
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
InjectBOTA_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:
~/.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: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
~/.bota/config.json.
Commands
End Users
Provider integrations
Manage project-scoped ASR/LLM provider credentials withintegrations: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:
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
--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
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:MCP server (stdio)
Use the existing local compatibility tools with the default mode: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:
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:
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:

