These commands are available in the published beatapi 0.3.0 CLI and
beatapi-client 0.3.0 package. Check beatapi --version and installed --help
when diagnosing an older installation; 0.2.0 does not have these commands.
beatapi auth login
beatapi auth status
beatapi capabilities search --query image --kind model --limit 5
beatapi capabilities search --query search --kind data --platform twitter --limit 5
beatapi capabilities search --kind workflow --limit 5
beatapi capabilities inspect <reference-returned-by-search>Login uses hidden terminal input and the OS credential manager. Agents must not
request the key in chat. Search and Inspect are anonymous catalog operations;
they do not validate a key. Use auth status for authenticated verification.
Search outputs {object, data, next_cursor} (the SDK unwraps the outer REST
data envelope once). Use --cursor to continue the search. Inspect emits
the actual contract as JSON; partial/unknown contract warnings go to stderr.
Do not assume the first social search result searches posts: inspect its meaning.
After inspecting the chosen reference, create an input JSON file matching that capability's actual schema. If Inspect is partial, consult the official API docs and OpenAPI first. The CLI does not fabricate, default or certify missing fields. The file contains only the capability input, not the reference/operation envelope.
beatapi capabilities run <reference> --file input.json --idempotency-key <unique-request-key>
beatapi capabilities status <same-reference> <returned-task-id> --wait --attempts 60 --interval 5000Angle-bracket values are placeholders, not runnable IDs. A start may spend money;
run it only for an authorized task. A missing idempotency key is generated and
printed to stderr before the request. Save and reuse that key and the same input
for a retry. The CLI never automatically retries a start. SDK retries are opt-in
and preserve the supplied key. Both start and status POST to
/v1/capabilities/run; status uses operation: status, not a separate URL.
Synchronous Data results are returned immediately: do not poll them. For an async result, use the returned task ID. Waiting stops on success, failure, manual-action states, unknown states, or the configured attempt limit. A timeout prints the last result and exits nonzero; resume status lookup, never create a new task to resume. Each capability HTTP request has a 35-second timeout and rejects redirects. Read-only status requests may retry transient errors up to three attempts.
All four commands emit JSON to stdout and accept --output new-file.json.
Output files use mode 0600 and are never overwritten. JSON is also emitted to
stdout before saving; if saving fails, retain that result, do not restart a task.
Progress/warnings go to stderr. Unknown/duplicate options are rejected.
Existing auth, files upload, workflow, tasks, webhook and realtime commands remain supported. CLI key storage does not configure an unrelated MCP host's credentials.
This additive capability surface follows the gateway's public three-tool manifest at https://beatapi.io/capabilities-mcp-tools.json and observed REST envelopes. The generated OpenAPI snapshot now includes capability, Social Data, and onboarding routes. Public capability projections keep incomplete schema fields optional; they do not claim every gateway entry provides a complete input or output contract.
Verification: HTTP-boundary tests cover discovery, partial schema handling, same-key start retries, status routing, synchronous results and bounded polling. No paid end-to-end result is implied by those tests. Live smoke should first run Search/Inspect; a real paid example needs its own recorded result and authorization.
As verified on 2026-09-22, production Search returned 60 Model capabilities, 1,000+ Data actions, and three Workflows when fully paginated. This is a dated observation, not a package constant or availability promise. Search again for every user task and choose only a current returned reference.