CLI

Install the current release on Linux or macOS:

Homebrew and Go source installations are also available:

On Windows, download the matching windows-amd64 or windows-arm64 archive from the latest CLI release, extract runapi.exe, and add it to PATH.

Pin the installer to a version or an installation directory when a deployment requires a reproducible binary:

The installer also accepts RUNAPI_VERSION, RUNAPI_INSTALL_DIR, RUNAPI_INSTALL_BASE, RUNAPI_DOWNLOAD_BASE, and RUNAPI_SKIP_LIBC_CHECK=1.

On a workstation, sign in in the browser and confirm the credential source:

Run a model action with an inline JSON input or a JSON file:

Most model actions are asynchronous. They wait for a terminal result by default; add --async to return the Task immediately and use wait later:

Every command emits JSON on standard output unless an option explicitly requests a scalar value, such as files create --url-only or listen --print-secret. Progress and diagnostic messages stay on standard error, so JSON can safely flow to jq:

Model actions accept exactly one request input source:

Use runapi <service> <action> --help before constructing a request. The installed CLI lists the action’s current fields, accepted model identifiers, and validation constraints.

These global options apply to every command:

The model command shape is runapi <service> <action>. Synchronous actions return their response immediately. For asynchronous actions, the default behavior is submit, poll, and return the terminal Task result; --async returns the creation response instead.

For top-level media URL fields, a readable local file path is uploaded before the model action runs. Existing http:// and https:// URLs are sent unchanged. Use files create when you need a reusable temporary URL, when the source is a remote URL, or when the source is Base64 data.

The list above is the complete action inventory in this CLI release. Each action’s exact request and response contract is available in the API Reference, and its local command help is the source for version-specific fields.

Use get to inspect the current state of an asynchronous Task without waiting. Use wait to poll until it completes, fails, or reaches the command timeout. Both commands require the original service and action so the CLI can select the correct Task result shape.

runapi files create uploads exactly one source and returns a temporary URL that expires after one hour. Its source can be a local path, a remote URL, or Base64 data.

The source choices are mutually exclusive. --url-only prints the URL alone; omit it to receive the full JSON response.

Inspect the authenticated user and selected Account, then query balance and spend counters:

pricing list reads current Price Schedules. Filter by service, action, or model. pricing quote estimates the Task reservation for a required service and action; add --model when the action is model-specific and provide Pricing Inputs with --params or --params-file.

Pricing commands do not require credentials unless the quote refers to an Account-owned source Task.

runapi login opens a browser authorization flow and saves the resulting credential. For servers and CI, auth import-token accepts an API key from standard input, verifies it by default, and saves it without exposing the value in the process list or shell history:

auth import-token --skip-verify supports offline image setup. Use it only when verification cannot run during setup; auth status verifies the active credential later.

API key precedence is --api-key, then RUNAPI_API_KEY, then the local CLI configuration file. Base URL precedence is --base-url, then RUNAPI_BASE_URL, then the saved base URL, then https://runapi.ai. The configuration file is ~/.config/runapi/config.json, or $XDG_CONFIG_HOME/runapi/config.json when XDG_CONFIG_HOME is set.

runapi listen receives Task callbacks for one selected API key and optionally forwards each signed callback to a local HTTP endpoint. Browser login is required before using listener operations.

The positional URL and --forward-to are alternatives. The listener writes each signed callback body to standard output. A Task with callback_url continues to deliver to that URL and is also copied to the local listener.

After receiving a valid listener event, the CLI acknowledges it before attempting the local HTTP request. Each event is forwarded locally once: non-2xx responses and connection errors are reported in the terminal, but they do not make the listener replay the event. This local debugging behavior does not change delivery retries for a Task’s callback_url.

Each Account can run up to 100 active listeners per Callback Subscription Key and 1,000 active listeners in total. When a limit is reached, stop an idle listener or wait and try again. The API response identifies whether the selected key, your Account, or the overall service capacity is full.

An idle listener checks for new events about every 15 to 30 seconds. Events are normally found within about 15 seconds and are read immediately when available. If a limit is reached, stop an idle listener or wait and try again. Existing delivery and acknowledgement behavior is unchanged.

Key selection is, in order: --callback-api-key-id for one command, callback_api_key_id in the project .runapi.toml, then an interactive selector. The project configuration is saved at the Git root, or the current directory outside a Git repository, and contains only the stable ID:

Print a selected key’s Listen Signing Secret without starting a listener, or rotate it after exposure:

Rotation invalidates active listeners for that selected key. Update every local verifier with the newly printed secret before restarting its listener.

Install the portable RunAPI CLI skill into a supported Harness, inspect supported targets, or remove an installed skill:

Built-in targets are claude, codex, gemini, openclaw, and hermes. install-skill accepts --version to pin a skill release, --target-dir for a custom destination, --source for a source repository, and --force to overwrite an existing skill directory.

Generate completion scripts for Bash, Zsh, Fish, or PowerShell. For example, load Bash completion in the current shell:

Use runapi --help to list commands, runapi <command> --help for a command’s options, and runapi <service> <action> --help for a model action’s fields.

Commands exit with a non-zero code that scripts can handle:

For request fields, Task status values, callback payloads, error bodies, and rate-limit handling, continue with the API Reference. Use SDKs when the same workflow belongs inside an application.