{"id":"259e2049-21c1-4434-bb60-585d9bc534bc","entityType":"agent","slug":"clawhub-runapi-ai-runapi-cli","name":"runapi-cli","canonicalUrl":"https://www.xpersona.co/agent/clawhub-runapi-ai-runapi-cli","canonicalPath":"/agent/clawhub-runapi-ai-runapi-cli","generatedAt":"2026-10-10T06:41:57.204Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T04:27:27.696Z","emptyReason":null},"description":"Use the RunAPI CLI for one-off artifacts and results, or RunAPI's standard x402 REST flow for wallet-funded Task calls without an API key. Use when an agent needs to discover models or prices, create a paid Task, poll its result, or run a supported CLI service. Use an SDK for app or production integration. Skill: runapi-cli Owner: runapi-ai Summary: Use the RunAPI CLI for one-off artifacts and results, or RunAPI's standard x402 REST flow for wallet-funded Task calls without an API key. Use when an agent needs to discover models or prices, create a paid Task, poll its result, or run a supported CLI service. Use an SDK for app or production integration. Tags: latest:0.3.1 Version history: v0.3.1 | 2026-09-28T05:47:14.718","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.7K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s1771k6pjxksnjws51x2htfjvd876syh:runapi-cli","sourceUrl":"https://clawhub.ai/runapi-ai/runapi-cli","homepage":"https://clawhub.ai/runapi-ai/skills/runapi-cli","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/runapi-ai/runapi-cli","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/runapi-ai/skills/runapi-cli","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":65,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Use the RunAPI CLI for one-off artifacts and results, or RunAPI's standard x402 REST flow for wallet-funded Task calls without an API key. Use when an agent nee"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T04:27:27.696Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T04:27:27.696Z","emptyReason":null},"stars":null,"forks":null,"downloads":1686,"packageName":null,"latestVersion":"0.3.1","tractionLabel":"1.7K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T04:27:27.696Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T04:27:27.696Z","lastCrawledAt":"2026-10-10T04:27:27.696Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T04:27:27.696Z","lastVerifiedAt":null,"highlights":[{"version":"0.3.1","createdAt":"2026-09-28T05:47:14.718Z","changelog":"## Added - Document x402 payment flows and Task polling for agent workflows using the RunAPI CLI.","fileCount":3,"zipByteSize":9448},{"version":"0.3.0","createdAt":"2026-08-17T09:48:24.689Z","changelog":"## Added - Guide agents through persistent File lifecycle commands and multipart Upload composition while preserving temporary file upload guidance.","fileCount":3,"zipByteSize":7135},{"version":"0.2.17","createdAt":"2026-08-14T13:00:21.975Z","changelog":"## Fixed - Remove the installation example that directs users to a deleted CLI release.","fileCount":3,"zipByteSize":6945},{"version":"0.2.16","createdAt":"2026-08-12T06:25:22.531Z","changelog":"## Changed - Select a listed service and operation from installed CLI help before reading the request contract or submitting a one-off task. - Route one-off results through installed CLI commands with synchronous defaults, explicit async requests, verified deliverables, and bounded recovery.","fileCount":3,"zipByteSize":6774},{"version":"0.2.15","createdAt":"2026-08-10T14:13:15.241Z","changelog":"## Changed - Complete marketplace distribution for the RunAPI CLI skill.","fileCount":3,"zipByteSize":6542},{"version":"0.2.14","createdAt":"2026-08-04T16:27:36.636Z","changelog":"## Changed - Explain local listener limits, idle polling timing, immediate event delivery, and retry guidance. - Document that local listeners honor the server's Retry-After delay when retrying.","fileCount":3,"zipByteSize":6547},{"version":"0.2.13","createdAt":"2026-07-31T09:55:46.333Z","changelog":"## Changed - Document the acknowledge-before-forward boundary and one-attempt handling for local HTTP failures.","fileCount":3,"zipByteSize":6462},{"version":"0.2.12","createdAt":"2026-07-28T04:45:21.374Z","changelog":"## Added - Document public Price Schedule and task reservation quote commands.","fileCount":3,"zipByteSize":5999}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1771k6pjxksnjws51x2htfjvd876syh:runapi-cli","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-runapi-ai-runapi-cli/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-runapi-ai-runapi-cli/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-runapi-ai-runapi-cli/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-runapi-ai-runapi-cli/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-runapi-ai-runapi-cli/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-runapi-ai-runapi-cli/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T06:41:57.199Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-runapi-ai-runapi-cli/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-runapi-ai-runapi-cli/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-runapi-ai-runapi-cli/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-runapi-ai-runapi-cli/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T04:27:27.696Z","emptyReason":null},"readme":"Skill: runapi-cli\n\nOwner: runapi-ai\n\nSummary: Use the RunAPI CLI for one-off artifacts and results, or RunAPI's standard x402 REST flow for wallet-funded Task calls without an API key. Use when an agent needs to discover models or prices, create a paid Task, poll its result, or run a supported CLI service. Use an SDK for app or production integration.\n\nTags: latest:0.3.1\n\nVersion history:\n\nv0.3.1 | 2026-09-28T05:47:14.718Z | user\n\n## Added\n- Document x402 payment flows and Task polling for agent workflows using the RunAPI CLI.\n\nv0.3.0 | 2026-08-17T09:48:24.689Z | user\n\n## Added\n- Guide agents through persistent File lifecycle commands and multipart Upload composition while preserving temporary file upload guidance.\n\nv0.2.17 | 2026-08-14T13:00:21.975Z | user\n\n## Fixed\n- Remove the installation example that directs users to a deleted CLI release.\n\nv0.2.16 | 2026-08-12T06:25:22.531Z | user\n\n## Changed\n- Select a listed service and operation from installed CLI help before reading the request contract or submitting a one-off task.\n- Route one-off results through installed CLI commands with synchronous defaults, explicit async requests, verified deliverables, and bounded recovery.\n\nv0.2.15 | 2026-08-10T14:13:15.241Z | user\n\n## Changed\n- Complete marketplace distribution for the RunAPI CLI skill.\n\nv0.2.14 | 2026-08-04T16:27:36.636Z | user\n\n## Changed\n- Explain local listener limits, idle polling timing, immediate event delivery, and retry guidance.\n- Document that local listeners honor the server's Retry-After delay when retrying.\n\nv0.2.13 | 2026-07-31T09:55:46.333Z | user\n\n## Changed\n- Document the acknowledge-before-forward boundary and one-attempt handling for local HTTP failures.\n\nv0.2.12 | 2026-07-28T04:45:21.374Z | user\n\n## Added\n- Document public Price Schedule and task reservation quote commands.\n\nv0.2.11 | 2026-07-20T08:10:06.987Z | user\n\n## Changed\n- Document explicit per-key Listen Signing Secret rotation without replacing the business API key.\n- Require local verifier updates and listener restarts after rotation.\n\nv0.2.10 | 2026-07-17T08:05:09.722Z | user\n\n## Changed\n- Document JSON API key discovery, explicit stable-ID selection, strict project configuration, and per-key listener secret retrieval.\n- Guide agents through login-required, missing-selection, cross-member configuration, and unusable-key recovery without silently selecting another key.\n- Require listener users upgrading from the previous behavior to update the CLI, log in again, replace the webhook secret, and restart listeners.\n\nv0.2.5 | 2026-05-23T18:38:40.616Z | user\n\nAgent-facing CLI-first redesign\n\nArchive index:\n\nArchive v0.3.1: 3 files, 9448 bytes\n\nFiles: skill-card.md (1994b), SKILL.md (20365b), _meta.json (129b)\n\nFile v0.3.1:SKILL.md\n\n---\nname: runapi-cli\ndescription: Use the RunAPI CLI for one-off artifacts and results, or RunAPI's standard x402 REST flow for wallet-funded Task calls without an API key. Use when an agent needs to discover models or prices, create a paid Task, poll its result, or run a supported CLI service. Use an SDK for app or production integration.\ndocumentation: https://runapi.ai/models.md\ncatalog: https://runapi.ai/models.md\nmetadata:\n  openclaw:\n    homepage: https://runapi.ai/models\n    primaryEnv: RUNAPI_API_KEY\n    requires:\n      bins:\n      - runapi\n    install:\n    - kind: brew\n      formula: runapi-ai/tap/runapi\n      bins:\n      - runapi\n    envVars:\n    - name: RUNAPI_API_KEY\n      required: false\n      description: Optional RunAPI API key; agents should prefer environment auth or saved shared config for headless use. Browser login can be completed with `runapi login` or the MCP `login` tool.\n---\n\n# RunAPI CLI\n\nThe `runapi` CLI executes one-off artifacts or results only for services in its\ninstalled command catalog. An app, backend, worker, library, or production code\nintegration uses a RunAPI SDK instead.\n\n## Choose route\n\nUse the CLI for a one-off artifact or result. Use an SDK for an app, backend,\nworker, library, or production code. Before composing a service command,\ndiscover the installed command catalog with `runapi --help`; proceed only when\nit lists the service. An absent service routes to its SDK or public API contract,\nnot to a guessed CLI command.\n\n## Install\n\n| Target | Command |\n|---|---|\n| macOS / Linux (interactive) | `brew install runapi-ai/tap/runapi` |\n| Server / CI (headless) | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh` |\n\nThe installer detects OS and architecture (Linux and macOS, amd64 and arm64), verifies a SHA-256 checksum from `https://runapi.ai/cli/latest.json`, and refuses to write the binary if verification fails.\n\n## Authentication\n\nCheck the current state first:\n\n```shell\nrunapi auth status\n```\n\n| Source | How |\n|---|---|\n| Environment (agent/headless default) | Read `RUNAPI_API_KEY` from the environment |\n| Saved config (agent/server/CI) | `printf '%s' \"$RUNAPI_API_KEY\" \\| runapi auth import-token --token -` (writes `~/.config/runapi/config.json` with mode 0600) |\n| Browser login (interactive fallback) | `runapi login` in a terminal, or the MCP `login` tool from an MCP host |\n\n`RUNAPI_BASE_URL` overrides the default base URL.\n\nThe RunAPI MCP Server reads the same `~/.config/runapi/config.json` as the CLI. After `runapi login` or the MCP `login` tool completes, authenticated MCP tools can use the saved credentials after the host reloads config if needed.\n\nAvoid `runapi auth import-token --token \"$KEY\"` directly — the value would be visible in `ps -ef` on shared hosts. Use stdin (`--token -`) or `RUNAPI_API_KEY` in the environment.\n\n## Discover services, commands, and fields\n\nThe CLI is JSON-first: every service exposes typed commands, and each command\ndocuments its request fields through `--help`. Always inspect before composing a\nrequest instead of guessing flags.\n\n```shell\nrunapi --help\nrunapi suno --help\nrunapi suno text-to-music --help\n```\n\nSelect capability in order: use `runapi --help` to choose a listed service,\nthen inspect `runapi <service> --help`. Choose `<action>` only from service help,\nthen inspect `runapi <service> <action> --help` for the current request contract,\nincluding nested fields and rules. Use only the listed service, action, model,\nfields, and conditional combinations.\n\n## Run a model\n\nWrite valid JSON to a file and pass it with `--input-file`. The default command\nwaits synchronously and polls until the task completes. Use inline `--input` or\nstdin only when the caller specifically needs that transport.\n\n```shell\n# Synchronous: submit and poll until done\nrunapi suno text-to-music --input-file request.json\n\n# Asynchronous: submit and return immediately, then poll separately\nrunapi suno text-to-music --async --input-file request.json\nrunapi wait <task-id> --service suno --action text-to-music\n\n# Inspect a task without waiting\nrunapi get <task-id> --service suno --action text-to-music\n```\n\nUse `--async` only when the user explicitly requests background execution,\npolling, or webhook integration. Preserve the returned task ID and use the exact\nservice/action pair from the submitted command for `get` or `wait`.\n\nJSON responses go to stdout; progress lines go to stderr. Pipe to `jq` for downstream parsing.\n\n## Account\n\n```shell\nrunapi account info\nrunapi account balance\n```\n\n## Live pricing\n\nPricing commands return current estimates for paid tasks. `pricing list` and\nordinary `pricing quote` calls do not require an API key. A quote with an\nAccount-owned `source_task_id` follows the normal API-key authentication rules.\n\n```shell\nrunapi pricing list --service suno\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params '{\"vocal_mode\":\"auto_lyrics\",\"prompt\":\"A chill lo-fi beat\"}'\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params-file pricing-inputs.json\n```\n\n## Self-funded x402 REST calls (no API key)\n\nUse this route when the agent has a wallet and must pay for a supported Task\nendpoint directly. It is REST-only; the CLI and MCP server do not add an x402\ntransport. Do not register, create an API key, buy credits, or create a Task\nbefore payment.\n\nUse the x402 v2 client provided by the agent runtime or wallet platform. An\navailable wallet signer and x402 v2 client are prerequisites; otherwise stop\nand report the missing prerequisite. Use standard x402 signing; the API-key\npath remains a separate authentication route.\n\n### Prerequisites and discovery\n\nThe agent platform owns the wallet and signing operation. The wallet must hold\nUSDC on Base mainnet (`eip155:8453`), and the signing key must stay in the\nplatform's secure wallet boundary. The v1 asset is USDC contract\n`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.\n\nDiscover models and unauthenticated public prices before spending:\n\n```shell\nBASE_URL=\"${RUNAPI_BASE_URL:-https://runapi.ai}\"\ncurl -fsS \"$BASE_URL/api/v1/models\"\ncurl -fsS \"$BASE_URL/api/v1/price_schedules?service=suno&action=text_to_music&model=suno-v4\"\ncurl -fsS -X POST \"$BASE_URL/api/v1/price_quotes\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n  \"service\":\"suno\",\n  \"action\":\"text_to_music\",\n  \"model\":\"suno-v4\",\n  \"params\":{\n    \"prompt\":\"A chill lo-fi beat\"\n  }\n}'\n```\n\nOnly an endpoint whose billing shape is `per_call`, has `unit_price_cents`, and\nis at most 10 USDC is automatically eligible. The price response is discovery\ndata; the payment amount, asset, recipient, and network come only from the\n`accepts` entry in the `PAYMENT-REQUIRED` challenge returned by the actual Task\nrequest. That challenge is valid for 300 seconds.\n\nCompletion criterion: the wallet is on Base mainnet with enough USDC, the\nendpoint is eligible from the live price contract, and the exact Task request\nis preserved for signing and replay.\n\n### Standard x402 v2 request\n\nSend the normal JSON request without an API key, preserving the exact method,\nURL, and body for a possible retry:\n\n```shell\ncurl -i -X POST \"$BASE_URL/api/v1/suno/text_to_music\" \\\n  -H 'Content-Type: application/json' \\\n  --data @request.json\n```\n\nFor a supported paid Task endpoint, the first response is `402` with the\nstandard `PAYMENT-REQUIRED` header. Pass that header to an existing x402 v2\nclient connected to the agent wallet. The client signs the requirements and\nreplays the same request with `PAYMENT-SIGNATURE`; do not invent an opt-in\nheader, `202` payment protocol, Capability, Payment Attempt, or private\nRunAPI header. Conceptually:\n\n```text\nrequest = {method: POST, url: task_url, json: payload}\nresponse = x402_client.send(request, wallet=agent_wallet)\n# The client handles 402, PAYMENT-REQUIRED, signing, and the retry:\n#   retry request header: PAYMENT-SIGNATURE: <client-generated value>\nassert response.status == 200\n# settlement evidence is in PAYMENT-RESPONSE; keep it with the task record\n```\n\nOn success, RunAPI returns the endpoint's ordinary `200` body and the standard\n`PAYMENT-RESPONSE` header. Decode that header only with the x402 client; never\nlog or expose `PAYMENT-SIGNATURE`. A `200` body may describe a still-processing\nTask: asynchronous result delivery is a RunAPI Task contract, not an x402\nprotocol status. Before payment, RunAPI only validates parameters and price;\nit does not download or process media.\n\nCompletion criterion: the retry returns HTTP `200`, the settlement evidence is\nretained, and the signed payment value is absent from logs.\n\nThe authentication split is intentional: a valid API key keeps using credits;\na supported paid Task endpoint without credentials uses x402 and returns\n`402`; other endpoints without credentials remain `401`. Payment validation\nfailure also remains `402`. x402 creates no API key, credits balance, login, or\nMCP capability.\n\n### Read the bound Task\n\nThe successful `200` body adds one access grant to the endpoint's ordinary\nresponse; other endpoint-specific fields remain present:\n\n```json\n{\n  \"task_id\": \"task_123\",\n  \"access_token\": \"tat_abc...\",\n  \"poll_url\": \"https://runapi.ai/api/v1/tasks/task_123?access_token=tat_abc...\"\n}\n```\n\nCompletion criterion: the agent has saved `task_id`, `access_token`, and the\nverbatim `poll_url` from the same successful response.\n\nSave `poll_url` verbatim and repeatedly `GET` it; the query-string token is\nthe intended authentication mechanism. It is a read-only grant for exactly\none Task and cannot read an account, list Tasks, or write anything:\n\n```shell\ncurl -fsS \"$POLL_URL\"\n```\n\nCompletion criterion: polling ends only at a terminal Task status or a defined\n`404`/transport failure; a processing response is never treated as final.\n\nThe query response is:\n\n```json\n{\"id\":\"task_123\",\"status\":\"processing\"}\n```\n\nKeep polling with a bounded delay while the returned status is non-terminal.\nWhen terminal, `completed` includes `response` with the result's HTTP\nstatus, content type, headers, and body; `failed` includes the terminal error\nresponse when retained. Do not replace the poll URL with an API-key request or\nassume the payment itself is a task result.\n\nThe `tat_` token is issued once and may be read repeatedly for that Task. It\nexpires 30 days after the Task reaches a terminal state. Invalid, expired, and\nwrong-Task tokens all return `404`; do not retry those as authentication or\npayment failures.\n\nCompletion criterion: the agent has either received the terminal result or\nrecorded the exact terminal/error state for the operator.\n\n### Failed Task and manual refund\n\nIf a settled x402 Task reaches terminal `failed`, RunAPI records one full-amount\nmanual refund obligation for the actual received USDC atomic amount. This is\nan operations workflow: an authorized operator sends the on-chain refund. There is no automatic chain refund and no\nrefund page required. Preserve the Task ID, settlement transaction hash,\npayer wallet, network, amount, and `PAYMENT-RESPONSE` for the operator.\n\nDo not promise a refund for a processing Task, an unknown settlement, or a\ncallback-delivery failure; those states do not create this terminal-failure\nobligation.\n\nCompletion criterion: for terminal `failed`, the agent has retained the\nsettlement evidence and submitted the refund facts to the authorized operator;\nit does not claim that a refund was executed.\n\n## Local callback listeners\n\nListener access requires the credential issued by `runapi login`; an ordinary imported API key cannot list callback candidates, read a Listen Signing Secret, or open a listener. This restriction applies only to listener operations: ordinary API keys can still create and query tasks.\n\nBefore running a listener from an agent, check the saved auth and list the current member's key metadata:\n\n```shell\nrunapi auth status\nrunapi api-keys list --json\n```\n\nIf the API returns `cli_listen_required`, explain that the imported key keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override, then complete `runapi login` in their terminal (or the MCP `login` tool) and retry `runapi listen`. Do not retry with an imported API key or a management key.\n\nEach candidate contains `id`, `name`, `masked_token`, and `enabled`. Select an enabled stable `id`; names and masks are display context only, so renaming a key does not invalidate a stored selection. When more than one enabled key is available and the project does not identify one, present the candidates to the user instead of choosing one silently.\n\nSelection precedence is:\n\n1. `--callback-api-key-id <id>` for this invocation. It does not rewrite project config.\n2. `callback_api_key_id` from `.runapi.toml` at the git root, or from the current directory outside a git repository.\n3. The TTY selector. It writes the selected ID only after the server validates the listener session.\n\nNon-TTY invocations never select automatically. Without a flag or config, the `callback_api_key_required` error includes the candidate list so an agent can choose explicitly.\n\nProject config has one allowed field and is safe to commit:\n\n```toml\ncallback_api_key_id = \"token_abc123\"\n```\n\nDo not add credentials, key names, masks, signing secrets, forwarding URLs, or `base_url` to `.runapi.toml`; unknown fields are rejected.\n\nPass the selected ID explicitly from an agent. The listener receives only tasks created with that API key:\n\n```shell\nrunapi listen localhost:3000/webhooks/runapi --callback-api-key-id token_abc123\n```\n\nThe CLI acknowledges each valid listener event before attempting the local HTTP request. It forwards each event locally once and reports non-2xx responses or connection errors without requesting a listener replay. This local debugging behavior does not change delivery retries for a Task's `callback_url`.\n\nEach Account can run up to 100 active listeners per Callback Subscription Key and 1,000 in total. When a limit is reached, stop an idle listener or wait and retry; the response identifies which limit is full. The CLI honors the server's `Retry-After` delay when present. Idle polling checks for events about every 15 to 30 seconds. Events are normally found within about 15 seconds and are read immediately when available.\n\nStartup output identifies the selected key by name, ID, and mask, prints the absolute project config path, and prints that key's stable Listen Signing Secret. To inject the secret without starting a listener, keep it out of logs and project config:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --print-secret --callback-api-key-id token_abc123)\"\n```\n\nIf the secret is exposed, rotate only the selected key's Listen Signing Secret:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --rotate-secret --callback-api-key-id token_abc123)\"\n```\n\nThis invalidates every active listener using the selected key without rotating its business API credential. Update each local verifier with the printed secret, then restart those listeners.\n\nRecovery rules:\n\n- A committed ID owned by another member is not reusable. Run `runapi api-keys list --json`, select that member's key, and pass its ID explicitly. Update the one-line project config only when the project should adopt that member-specific selection.\n- `callback_api_key_unusable` means the selected key was disabled, discarded, or lost membership. The listener exits without falling back; list keys and select another one explicitly.\n- After upgrading from the previous listener behavior, update the CLI, run `runapi login` again, restart listeners, and replace the old local webhook secret.\n\n## Files and Uploads\n\nPass an agent-readable local path directly to a top-level media URL field. The\nCLI uploads the file before submitting the request and replaces the field value\nwith the temporary URL. Remote `http://` and `https://` values stay unchanged.\n\nUse `runapi files create` only for a reusable URL, Base64 input, or a\ncontract-required upload. This temporary upload command returns a URL and\nremains available unchanged.\n\n```shell\nrunapi files create ./image.png --file-name image.png\nrunapi files create --url https://cdn.runapi.ai/public/samples/mask.png --file-name image.png\nrunapi files create --base64 \"$BASE64_IMAGE\" --file-name image.png\n```\n\nThe command returns JSON with `file_name`, `url`, `size_bytes`, `mime_type`, `created_at`, and `expires_at`. The returned `url` is a one-hour temporary File Upload URL. Use it in endpoint fields that accept media URLs; check the model/action docs for the exact field name. Add `--url-only` when a script needs only the temporary URL on stdout.\n\nUse persistent Files when the caller needs a stable File ID instead of a URL.\nInspect each command before composing it:\n\n```shell\nrunapi files create-file ./knowledge.pdf\nrunapi files list --order desc\nrunapi files retrieve file_123\nrunapi files content file_123 --output ./knowledge-copy.pdf\nrunapi files delete file_123\n```\n\nUse multipart Uploads to send Parts before composing the final File. Preserve\nPart ID order when retrying an uncertain completion response:\n\n```shell\nrunapi uploads create --bytes 1048576 --filename archive.bin --mime-type application/octet-stream\nrunapi uploads add-part upload_123 ./archive.part-01\nrunapi uploads complete upload_123 --part-id part_123\nrunapi uploads cancel upload_123\n```\n\nInspect `runapi files --help`, `runapi uploads --help`, and each selected\nsubcommand's help for the installed lifecycle contract.\n\n## Install the skill into another agent runtime\n\n```shell\nrunapi agent install-skill --target claude    # ~/.claude/skills/runapi-cli/\nrunapi agent install-skill --target codex     # ~/.codex/skills/runapi-cli/\nrunapi agent install-skill --target gemini    # ~/.gemini/skills/runapi-cli/\nrunapi agent install-skill --target openclaw  # ~/.openclaw/skills/runapi-cli/\nrunapi agent list-targets                     # JSON list with resolved paths\nrunapi agent install-skill --target-dir <path>  # custom location\n```\n\n## Troubleshooting CLI/skill drift\n\nThis skill is installed independently from the `runapi` binary and usually\ntracks the newest CLI behavior. If a command, action, flag, or input field\ndescribed here is unavailable or behaves differently, check the installed CLI\nversion and update it before changing the request:\n\n```shell\nrunapi version\nbrew upgrade runapi-ai/tap/runapi\n# or reinstall\ncurl -fsSL https://runapi.ai/cli/install.sh | sh\n```\n\nAfter updating, inspect the command help again:\n\n```shell\nrunapi --help\nrunapi <service> --help\nrunapi <service> <action> --help\n```\n\n## Safety notes for agents\n\n- Never paste API keys into example commands. Reference `RUNAPI_API_KEY` or `runapi auth import-token` instead.\n- Do not run interactive `runapi login` by default from an agent. In MCP hosts, guide the user through the `login` tool; in terminal/headless contexts, prefer `runapi auth status`, `RUNAPI_API_KEY`, and stdin token import unless the user explicitly wants browser auth.\n- Listener operations are the exception: when they return `cli_listen_required`, an imported key cannot recover. Explain that it keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override and complete browser-backed login; never store the returned credential or Listen Signing Secret in `.runapi.toml`.\n- The CLI exits non-zero on validation failures, network errors, and timeouts. Check the exit code before assuming success.\n- RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.\n\n## Verify, recover, or stop\n\nVerify every requested deliverable: download every URL, require a non-empty\nfile, and check the expected MIME type. A successful task status without the\nrequested files is incomplete.\n\nMake at most one evidence-backed request-shape correction, using the current\ncommand help or a structured validation error. Retry a transient transport\nfailure once only when no task was created, no usage was billed, and replay is\nsafe. Record a terminal service or provider failure and stop without changing\nthe model or action.\n\n## References\n\n- Browse every RunAPI model and its CLI service: https://runapi.ai/models.md\n\nFile v0.3.1:_meta.json\n\n{\n  \"ownerId\": \"kn70me4rk7jqjt92evshjeb5z18768g7\",\n  \"slug\": \"runapi-cli\",\n  \"version\": \"0.3.1\",\n  \"publishedAt\": 1790574434718\n}\n\nFile v0.3.1:skill-card.md\n\n## Description:\n\nGuides agents in discovering RunAPI services and pricing, running one-off tasks with the CLI, and making wallet-funded x402 Task calls through the REST API.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[runapi-ai](https://clawhub.ai/user/runapi-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use this skill to find RunAPI models and prices, run supported one-off CLI tasks, or pay for and poll eligible REST tasks with an agent wallet.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: A remote installer may execute unreviewed code.\n\nMitigation: Prefer the package-manager install; inspect or verify the remote installer before using the curl-to-shell option.\n\nRisk: Task inputs and uploaded files are sent to RunAPI.\n\nMitigation: Use the skill only with data that may be shared with RunAPI.\n\nRisk: Wallet-funded tasks may incur charges.\n\nMitigation: Check live pricing and confirm each paid task before spending.\n\nRisk: API keys, payment signatures, and listener secrets could be exposed.\n\nMitigation: Keep secrets out of logs and project files; use environment or secure wallet authentication.\n\n## Reference(s):\n\n- [RunAPI model and CLI service documentation](https://runapi.ai/models.md)\n- [RunAPI model catalog](https://runapi.ai/models)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Shell commands, Configuration instructions]\n\n**Output Format:** [Markdown with shell commands and JSON examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [CLI responses are JSON; task results and generated file links come from RunAPI.]\n\n## Skill Version(s):\n\n0.3.1 (source: ClawHub release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.3.0: 3 files, 7135 bytes\n\nFiles: skill-card.md (2204b), SKILL.md (14063b), _meta.json (129b)\n\nFile v0.3.0:SKILL.md\n\n---\nname: runapi-cli\ndescription: Install and use the RunAPI CLI for one-off artifacts and results from registered CLI-backed services. Use when the user asks an agent to inspect installed commands, run a supported service, pass JSON request bodies, wait for tasks, or automate a supported RunAPI workflow from the terminal. Use an SDK for app or production integration.\ndocumentation: https://runapi.ai/models.md\ncatalog: https://runapi.ai/models.md\nmetadata:\n  openclaw:\n    homepage: https://runapi.ai/models\n    primaryEnv: RUNAPI_API_KEY\n    requires:\n      bins:\n      - runapi\n    install:\n    - kind: brew\n      formula: runapi-ai/tap/runapi\n      bins:\n      - runapi\n    envVars:\n    - name: RUNAPI_API_KEY\n      required: false\n      description: Optional RunAPI API key; agents should prefer environment auth or saved shared config for headless use. Browser login can be completed with `runapi login` or the MCP `login` tool.\n---\n\n# RunAPI CLI\n\nThe `runapi` CLI executes one-off artifacts or results only for services in its\ninstalled command catalog. An app, backend, worker, library, or production code\nintegration uses a RunAPI SDK instead.\n\n## Choose route\n\nUse the CLI for a one-off artifact or result. Use an SDK for an app, backend,\nworker, library, or production code. Before composing a service command,\ndiscover the installed command catalog with `runapi --help`; proceed only when\nit lists the service. An absent service routes to its SDK or public API contract,\nnot to a guessed CLI command.\n\n## Install\n\n| Target | Command |\n|---|---|\n| macOS / Linux (interactive) | `brew install runapi-ai/tap/runapi` |\n| Server / CI (headless) | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh` |\n\nThe installer detects OS and architecture (Linux and macOS, amd64 and arm64), verifies a SHA-256 checksum from `https://runapi.ai/cli/latest.json`, and refuses to write the binary if verification fails.\n\n## Authentication\n\nCheck the current state first:\n\n```shell\nrunapi auth status\n```\n\n| Source | How |\n|---|---|\n| Environment (agent/headless default) | Read `RUNAPI_API_KEY` from the environment |\n| Saved config (agent/server/CI) | `printf '%s' \"$RUNAPI_API_KEY\" \\| runapi auth import-token --token -` (writes `~/.config/runapi/config.json` with mode 0600) |\n| Browser login (interactive fallback) | `runapi login` in a terminal, or the MCP `login` tool from an MCP host |\n\n`RUNAPI_BASE_URL` overrides the default base URL.\n\nThe RunAPI MCP Server reads the same `~/.config/runapi/config.json` as the CLI. After `runapi login` or the MCP `login` tool completes, authenticated MCP tools can use the saved credentials after the host reloads config if needed.\n\nAvoid `runapi auth import-token --token \"$KEY\"` directly — the value would be visible in `ps -ef` on shared hosts. Use stdin (`--token -`) or `RUNAPI_API_KEY` in the environment.\n\n## Discover services, commands, and fields\n\nThe CLI is JSON-first: every service exposes typed commands, and each command\ndocuments its request fields through `--help`. Always inspect before composing a\nrequest instead of guessing flags.\n\n```shell\nrunapi --help\nrunapi suno --help\nrunapi suno text-to-music --help\n```\n\nSelect capability in order: use `runapi --help` to choose a listed service,\nthen inspect `runapi <service> --help`. Choose `<action>` only from service help,\nthen inspect `runapi <service> <action> --help` for the current request contract,\nincluding nested fields and rules. Use only the listed service, action, model,\nfields, and conditional combinations.\n\n## Run a model\n\nWrite valid JSON to a file and pass it with `--input-file`. The default command\nwaits synchronously and polls until the task completes. Use inline `--input` or\nstdin only when the caller specifically needs that transport.\n\n```shell\n# Synchronous: submit and poll until done\nrunapi suno text-to-music --input-file request.json\n\n# Asynchronous: submit and return immediately, then poll separately\nrunapi suno text-to-music --async --input-file request.json\nrunapi wait <task-id> --service suno --action text-to-music\n\n# Inspect a task without waiting\nrunapi get <task-id> --service suno --action text-to-music\n```\n\nUse `--async` only when the user explicitly requests background execution,\npolling, or webhook integration. Preserve the returned task ID and use the exact\nservice/action pair from the submitted command for `get` or `wait`.\n\nJSON responses go to stdout; progress lines go to stderr. Pipe to `jq` for downstream parsing.\n\n## Account\n\n```shell\nrunapi account info\nrunapi account balance\n```\n\n## Live pricing\n\nPricing commands return current estimates for paid tasks. `pricing list` and\nordinary `pricing quote` calls do not require an API key. A quote with an\nAccount-owned `source_task_id` follows the normal API-key authentication rules.\n\n```shell\nrunapi pricing list --service suno\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params '{\"vocal_mode\":\"auto_lyrics\",\"prompt\":\"A chill lo-fi beat\"}'\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params-file pricing-inputs.json\n```\n\n## Local callback listeners\n\nListener access requires the credential issued by `runapi login`; an ordinary imported API key cannot list callback candidates, read a Listen Signing Secret, or open a listener. This restriction applies only to listener operations: ordinary API keys can still create and query tasks.\n\nBefore running a listener from an agent, check the saved auth and list the current member's key metadata:\n\n```shell\nrunapi auth status\nrunapi api-keys list --json\n```\n\nIf the API returns `cli_listen_required`, explain that the imported key keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override, then complete `runapi login` in their terminal (or the MCP `login` tool) and retry `runapi listen`. Do not retry with an imported API key or a management key.\n\nEach candidate contains `id`, `name`, `masked_token`, and `enabled`. Select an enabled stable `id`; names and masks are display context only, so renaming a key does not invalidate a stored selection. When more than one enabled key is available and the project does not identify one, present the candidates to the user instead of choosing one silently.\n\nSelection precedence is:\n\n1. `--callback-api-key-id <id>` for this invocation. It does not rewrite project config.\n2. `callback_api_key_id` from `.runapi.toml` at the git root, or from the current directory outside a git repository.\n3. The TTY selector. It writes the selected ID only after the server validates the listener session.\n\nNon-TTY invocations never select automatically. Without a flag or config, the `callback_api_key_required` error includes the candidate list so an agent can choose explicitly.\n\nProject config has one allowed field and is safe to commit:\n\n```toml\ncallback_api_key_id = \"token_abc123\"\n```\n\nDo not add credentials, key names, masks, signing secrets, forwarding URLs, or `base_url` to `.runapi.toml`; unknown fields are rejected.\n\nPass the selected ID explicitly from an agent. The listener receives only tasks created with that API key:\n\n```shell\nrunapi listen localhost:3000/webhooks/runapi --callback-api-key-id token_abc123\n```\n\nThe CLI acknowledges each valid listener event before attempting the local HTTP request. It forwards each event locally once and reports non-2xx responses or connection errors without requesting a listener replay. This local debugging behavior does not change delivery retries for a Task's `callback_url`.\n\nEach Account can run up to 100 active listeners per Callback Subscription Key and 1,000 in total. When a limit is reached, stop an idle listener or wait and retry; the response identifies which limit is full. The CLI honors the server's `Retry-After` delay when present. Idle polling checks for events about every 15 to 30 seconds. Events are normally found within about 15 seconds and are read immediately when available.\n\nStartup output identifies the selected key by name, ID, and mask, prints the absolute project config path, and prints that key's stable Listen Signing Secret. To inject the secret without starting a listener, keep it out of logs and project config:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --print-secret --callback-api-key-id token_abc123)\"\n```\n\nIf the secret is exposed, rotate only the selected key's Listen Signing Secret:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --rotate-secret --callback-api-key-id token_abc123)\"\n```\n\nThis invalidates every active listener using the selected key without rotating its business API credential. Update each local verifier with the printed secret, then restart those listeners.\n\nRecovery rules:\n\n- A committed ID owned by another member is not reusable. Run `runapi api-keys list --json`, select that member's key, and pass its ID explicitly. Update the one-line project config only when the project should adopt that member-specific selection.\n- `callback_api_key_unusable` means the selected key was disabled, discarded, or lost membership. The listener exits without falling back; list keys and select another one explicitly.\n- After upgrading from the previous listener behavior, update the CLI, run `runapi login` again, restart listeners, and replace the old local webhook secret.\n\n## Files and Uploads\n\nPass an agent-readable local path directly to a top-level media URL field. The\nCLI uploads the file before submitting the request and replaces the field value\nwith the temporary URL. Remote `http://` and `https://` values stay unchanged.\n\nUse `runapi files create` only for a reusable URL, Base64 input, or a\ncontract-required upload. This temporary upload command returns a URL and\nremains available unchanged.\n\n```shell\nrunapi files create ./image.png --file-name image.png\nrunapi files create --url https://cdn.runapi.ai/public/samples/mask.png --file-name image.png\nrunapi files create --base64 \"$BASE64_IMAGE\" --file-name image.png\n```\n\nThe command returns JSON with `file_name`, `url`, `size_bytes`, `mime_type`, `created_at`, and `expires_at`. The returned `url` is a one-hour temporary File Upload URL. Use it in endpoint fields that accept media URLs; check the model/action docs for the exact field name. Add `--url-only` when a script needs only the temporary URL on stdout.\n\nUse persistent Files when the caller needs a stable File ID instead of a URL.\nInspect each command before composing it:\n\n```shell\nrunapi files create-file ./knowledge.pdf\nrunapi files list --order desc\nrunapi files retrieve file_123\nrunapi files content file_123 --output ./knowledge-copy.pdf\nrunapi files delete file_123\n```\n\nUse multipart Uploads to send Parts before composing the final File. Preserve\nPart ID order when retrying an uncertain completion response:\n\n```shell\nrunapi uploads create --bytes 1048576 --filename archive.bin --mime-type application/octet-stream\nrunapi uploads add-part upload_123 ./archive.part-01\nrunapi uploads complete upload_123 --part-id part_123\nrunapi uploads cancel upload_123\n```\n\nInspect `runapi files --help`, `runapi uploads --help`, and each selected\nsubcommand's help for the installed lifecycle contract.\n\n## Install the skill into another agent runtime\n\n```shell\nrunapi agent install-skill --target claude    # ~/.claude/skills/runapi-cli/\nrunapi agent install-skill --target codex     # ~/.codex/skills/runapi-cli/\nrunapi agent install-skill --target gemini    # ~/.gemini/skills/runapi-cli/\nrunapi agent install-skill --target openclaw  # ~/.openclaw/skills/runapi-cli/\nrunapi agent list-targets                     # JSON list with resolved paths\nrunapi agent install-skill --target-dir <path>  # custom location\n```\n\n## Troubleshooting CLI/skill drift\n\nThis skill is installed independently from the `runapi` binary and usually\ntracks the newest CLI behavior. If a command, action, flag, or input field\ndescribed here is unavailable or behaves differently, check the installed CLI\nversion and update it before changing the request:\n\n```shell\nrunapi version\nbrew upgrade runapi-ai/tap/runapi\n# or reinstall\ncurl -fsSL https://runapi.ai/cli/install.sh | sh\n```\n\nAfter updating, inspect the command help again:\n\n```shell\nrunapi --help\nrunapi <service> --help\nrunapi <service> <action> --help\n```\n\n## Safety notes for agents\n\n- Never paste API keys into example commands. Reference `RUNAPI_API_KEY` or `runapi auth import-token` instead.\n- Do not run interactive `runapi login` by default from an agent. In MCP hosts, guide the user through the `login` tool; in terminal/headless contexts, prefer `runapi auth status`, `RUNAPI_API_KEY`, and stdin token import unless the user explicitly wants browser auth.\n- Listener operations are the exception: when they return `cli_listen_required`, an imported key cannot recover. Explain that it keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override and complete browser-backed login; never store the returned credential or Listen Signing Secret in `.runapi.toml`.\n- The CLI exits non-zero on validation failures, network errors, and timeouts. Check the exit code before assuming success.\n- RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.\n\n## Verify, recover, or stop\n\nVerify every requested deliverable: download every URL, require a non-empty\nfile, and check the expected MIME type. A successful task status without the\nrequested files is incomplete.\n\nMake at most one evidence-backed request-shape correction, using the current\ncommand help or a structured validation error. Retry a transient transport\nfailure once only when no task was created, no usage was billed, and replay is\nsafe. Record a terminal service or provider failure and stop without changing\nthe model or action.\n\n## References\n\n- Browse every RunAPI model and its CLI service: https://runapi.ai/models.md\n\nFile v0.3.0:_meta.json\n\n{\n  \"ownerId\": \"kn70me4rk7jqjt92evshjeb5z18768g7\",\n  \"slug\": \"runapi-cli\",\n  \"version\": \"0.3.0\",\n  \"publishedAt\": 1786960104689\n}\n\nFile v0.3.0:skill-card.md\n\n## Description:\n\nInstall and use the RunAPI CLI for one-off artifacts and results from registered CLI-backed services, while routing app or production integrations to a RunAPI SDK.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[runapi-ai](https://clawhub.ai/user/runapi-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use this skill to discover installed RunAPI CLI services, compose JSON request bodies, run or poll tasks, inspect account and pricing details, and manage file or callback workflows from the terminal.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill documents a mutable remote shell installer path that can execute changing code during installation.\n\nMitigation: Review before installing and prefer the documented Homebrew formula or another pinned, verifiable release path, especially in CI or environments with secrets.\n\nRisk: RunAPI credentials and webhook listener secrets may be exposed through command arguments, logs, or project files if handled carelessly.\n\nMitigation: Use environment variables or the documented private config, import tokens through stdin, and do not commit API keys, webhook secrets, key masks, forwarding URLs, or signing secrets.\n\n## Reference(s):\n\n- [RunAPI model and CLI catalog](https://runapi.ai/models.md)\n- [RunAPI models homepage](https://runapi.ai/models)\n- [ClawHub skill page](https://clawhub.ai/runapi-ai/skills/runapi-cli)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with shell command examples and JSON-oriented CLI instructions]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Includes guidance for CLI discovery, authentication, task polling, file handling, listener setup, and result verification.]\n\n## Skill Version(s):\n\n0.3.0 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.2.17: 3 files, 6945 bytes\n\nFiles: skill-card.md (2613b), SKILL.md (13133b), _meta.json (130b)\n\nFile v0.2.17:SKILL.md\n\n---\nname: runapi-cli\ndescription: Install and use the RunAPI CLI for one-off artifacts and results from registered CLI-backed services. Use when the user asks an agent to inspect installed commands, run a supported service, pass JSON request bodies, wait for tasks, or automate a supported RunAPI workflow from the terminal. Use an SDK for app or production integration.\ndocumentation: https://runapi.ai/models.md\ncatalog: https://runapi.ai/models.md\nmetadata:\n  openclaw:\n    homepage: https://runapi.ai/models\n    primaryEnv: RUNAPI_API_KEY\n    requires:\n      bins:\n      - runapi\n    install:\n    - kind: brew\n      formula: runapi-ai/tap/runapi\n      bins:\n      - runapi\n    envVars:\n    - name: RUNAPI_API_KEY\n      required: false\n      description: Optional RunAPI API key; agents should prefer environment auth or saved shared config for headless use. Browser login can be completed with `runapi login` or the MCP `login` tool.\n---\n\n# RunAPI CLI\n\nThe `runapi` CLI executes one-off artifacts or results only for services in its\ninstalled command catalog. An app, backend, worker, library, or production code\nintegration uses a RunAPI SDK instead.\n\n## Choose route\n\nUse the CLI for a one-off artifact or result. Use an SDK for an app, backend,\nworker, library, or production code. Before composing a service command,\ndiscover the installed command catalog with `runapi --help`; proceed only when\nit lists the service. An absent service routes to its SDK or public API contract,\nnot to a guessed CLI command.\n\n## Install\n\n| Target | Command |\n|---|---|\n| macOS / Linux (interactive) | `brew install runapi-ai/tap/runapi` |\n| Server / CI (headless) | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh` |\n\nThe installer detects OS and architecture (Linux and macOS, amd64 and arm64), verifies a SHA-256 checksum from `https://runapi.ai/cli/latest.json`, and refuses to write the binary if verification fails.\n\n## Authentication\n\nCheck the current state first:\n\n```shell\nrunapi auth status\n```\n\n| Source | How |\n|---|---|\n| Environment (agent/headless default) | Read `RUNAPI_API_KEY` from the environment |\n| Saved config (agent/server/CI) | `printf '%s' \"$RUNAPI_API_KEY\" \\| runapi auth import-token --token -` (writes `~/.config/runapi/config.json` with mode 0600) |\n| Browser login (interactive fallback) | `runapi login` in a terminal, or the MCP `login` tool from an MCP host |\n\n`RUNAPI_BASE_URL` overrides the default base URL.\n\nThe RunAPI MCP Server reads the same `~/.config/runapi/config.json` as the CLI. After `runapi login` or the MCP `login` tool completes, authenticated MCP tools can use the saved credentials after the host reloads config if needed.\n\nAvoid `runapi auth import-token --token \"$KEY\"` directly — the value would be visible in `ps -ef` on shared hosts. Use stdin (`--token -`) or `RUNAPI_API_KEY` in the environment.\n\n## Discover services, commands, and fields\n\nThe CLI is JSON-first: every service exposes typed commands, and each command\ndocuments its request fields through `--help`. Always inspect before composing a\nrequest instead of guessing flags.\n\n```shell\nrunapi --help\nrunapi suno --help\nrunapi suno text-to-music --help\n```\n\nSelect capability in order: use `runapi --help` to choose a listed service,\nthen inspect `runapi <service> --help`. Choose `<action>` only from service help,\nthen inspect `runapi <service> <action> --help` for the current request contract,\nincluding nested fields and rules. Use only the listed service, action, model,\nfields, and conditional combinations.\n\n## Run a model\n\nWrite valid JSON to a file and pass it with `--input-file`. The default command\nwaits synchronously and polls until the task completes. Use inline `--input` or\nstdin only when the caller specifically needs that transport.\n\n```shell\n# Synchronous: submit and poll until done\nrunapi suno text-to-music --input-file request.json\n\n# Asynchronous: submit and return immediately, then poll separately\nrunapi suno text-to-music --async --input-file request.json\nrunapi wait <task-id> --service suno --action text-to-music\n\n# Inspect a task without waiting\nrunapi get <task-id> --service suno --action text-to-music\n```\n\nUse `--async` only when the user explicitly requests background execution,\npolling, or webhook integration. Preserve the returned task ID and use the exact\nservice/action pair from the submitted command for `get` or `wait`.\n\nJSON responses go to stdout; progress lines go to stderr. Pipe to `jq` for downstream parsing.\n\n## Account\n\n```shell\nrunapi account info\nrunapi account balance\n```\n\n## Live pricing\n\nPricing commands return current estimates for paid tasks. `pricing list` and\nordinary `pricing quote` calls do not require an API key. A quote with an\nAccount-owned `source_task_id` follows the normal API-key authentication rules.\n\n```shell\nrunapi pricing list --service suno\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params '{\"vocal_mode\":\"auto_lyrics\",\"prompt\":\"A chill lo-fi beat\"}'\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params-file pricing-inputs.json\n```\n\n## Local callback listeners\n\nListener access requires the credential issued by `runapi login`; an ordinary imported API key cannot list callback candidates, read a Listen Signing Secret, or open a listener. This restriction applies only to listener operations: ordinary API keys can still create and query tasks.\n\nBefore running a listener from an agent, check the saved auth and list the current member's key metadata:\n\n```shell\nrunapi auth status\nrunapi api-keys list --json\n```\n\nIf the API returns `cli_listen_required`, explain that the imported key keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override, then complete `runapi login` in their terminal (or the MCP `login` tool) and retry `runapi listen`. Do not retry with an imported API key or a management key.\n\nEach candidate contains `id`, `name`, `masked_token`, and `enabled`. Select an enabled stable `id`; names and masks are display context only, so renaming a key does not invalidate a stored selection. When more than one enabled key is available and the project does not identify one, present the candidates to the user instead of choosing one silently.\n\nSelection precedence is:\n\n1. `--callback-api-key-id <id>` for this invocation. It does not rewrite project config.\n2. `callback_api_key_id` from `.runapi.toml` at the git root, or from the current directory outside a git repository.\n3. The TTY selector. It writes the selected ID only after the server validates the listener session.\n\nNon-TTY invocations never select automatically. Without a flag or config, the `callback_api_key_required` error includes the candidate list so an agent can choose explicitly.\n\nProject config has one allowed field and is safe to commit:\n\n```toml\ncallback_api_key_id = \"token_abc123\"\n```\n\nDo not add credentials, key names, masks, signing secrets, forwarding URLs, or `base_url` to `.runapi.toml`; unknown fields are rejected.\n\nPass the selected ID explicitly from an agent. The listener receives only tasks created with that API key:\n\n```shell\nrunapi listen localhost:3000/webhooks/runapi --callback-api-key-id token_abc123\n```\n\nThe CLI acknowledges each valid listener event before attempting the local HTTP request. It forwards each event locally once and reports non-2xx responses or connection errors without requesting a listener replay. This local debugging behavior does not change delivery retries for a Task's `callback_url`.\n\nEach Account can run up to 100 active listeners per Callback Subscription Key and 1,000 in total. When a limit is reached, stop an idle listener or wait and retry; the response identifies which limit is full. The CLI honors the server's `Retry-After` delay when present. Idle polling checks for events about every 15 to 30 seconds. Events are normally found within about 15 seconds and are read immediately when available.\n\nStartup output identifies the selected key by name, ID, and mask, prints the absolute project config path, and prints that key's stable Listen Signing Secret. To inject the secret without starting a listener, keep it out of logs and project config:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --print-secret --callback-api-key-id token_abc123)\"\n```\n\nIf the secret is exposed, rotate only the selected key's Listen Signing Secret:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --rotate-secret --callback-api-key-id token_abc123)\"\n```\n\nThis invalidates every active listener using the selected key without rotating its business API credential. Update each local verifier with the printed secret, then restart those listeners.\n\nRecovery rules:\n\n- A committed ID owned by another member is not reusable. Run `runapi api-keys list --json`, select that member's key, and pass its ID explicitly. Update the one-line project config only when the project should adopt that member-specific selection.\n- `callback_api_key_unusable` means the selected key was disabled, discarded, or lost membership. The listener exits without falling back; list keys and select another one explicitly.\n- After upgrading from the previous listener behavior, update the CLI, run `runapi login` again, restart listeners, and replace the old local webhook secret.\n\n## Temporary files\n\nPass an agent-readable local path directly to a top-level media URL field. The\nCLI uploads the file before submitting the request and replaces the field value\nwith the temporary URL. Remote `http://` and `https://` values stay unchanged.\n\nUse `runapi files create` only for a reusable URL, Base64 input, or a\ncontract-required upload.\n\n```shell\nrunapi files create ./image.png --file-name image.png\nrunapi files create --url https://cdn.runapi.ai/public/samples/mask.png --file-name image.png\nrunapi files create --base64 \"$BASE64_IMAGE\" --file-name image.png\n```\n\nThe command returns JSON with `file_name`, `url`, `size_bytes`, `mime_type`, `created_at`, and `expires_at`. The returned `url` is a one-hour temporary File Upload URL. Use it in endpoint fields that accept media URLs; check the model/action docs for the exact field name. Add `--url-only` when a script needs only the temporary URL on stdout.\n\n## Install the skill into another agent runtime\n\n```shell\nrunapi agent install-skill --target claude    # ~/.claude/skills/runapi-cli/\nrunapi agent install-skill --target codex     # ~/.codex/skills/runapi-cli/\nrunapi agent install-skill --target gemini    # ~/.gemini/skills/runapi-cli/\nrunapi agent install-skill --target openclaw  # ~/.openclaw/skills/runapi-cli/\nrunapi agent list-targets                     # JSON list with resolved paths\nrunapi agent install-skill --target-dir <path>  # custom location\n```\n\n## Troubleshooting CLI/skill drift\n\nThis skill is installed independently from the `runapi` binary and usually\ntracks the newest CLI behavior. If a command, action, flag, or input field\ndescribed here is unavailable or behaves differently, check the installed CLI\nversion and update it before changing the request:\n\n```shell\nrunapi version\nbrew upgrade runapi-ai/tap/runapi\n# or reinstall\ncurl -fsSL https://runapi.ai/cli/install.sh | sh\n```\n\nAfter updating, inspect the command help again:\n\n```shell\nrunapi --help\nrunapi <service> --help\nrunapi <service> <action> --help\n```\n\n## Safety notes for agents\n\n- Never paste API keys into example commands. Reference `RUNAPI_API_KEY` or `runapi auth import-token` instead.\n- Do not run interactive `runapi login` by default from an agent. In MCP hosts, guide the user through the `login` tool; in terminal/headless contexts, prefer `runapi auth status`, `RUNAPI_API_KEY`, and stdin token import unless the user explicitly wants browser auth.\n- Listener operations are the exception: when they return `cli_listen_required`, an imported key cannot recover. Explain that it keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override and complete browser-backed login; never store the returned credential or Listen Signing Secret in `.runapi.toml`.\n- The CLI exits non-zero on validation failures, network errors, and timeouts. Check the exit code before assuming success.\n- RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.\n\n## Verify, recover, or stop\n\nVerify every requested deliverable: download every URL, require a non-empty\nfile, and check the expected MIME type. A successful task status without the\nrequested files is incomplete.\n\nMake at most one evidence-backed request-shape correction, using the current\ncommand help or a structured validation error. Retry a transient transport\nfailure once only when no task was created, no usage was billed, and replay is\nsafe. Record a terminal service or provider failure and stop without changing\nthe model or action.\n\n## References\n\n- Browse every RunAPI model and its CLI service: https://runapi.ai/models.md\n\nFile v0.2.17:_meta.json\n\n{\n  \"ownerId\": \"kn70me4rk7jqjt92evshjeb5z18768g7\",\n  \"slug\": \"runapi-cli\",\n  \"version\": \"0.2.17\",\n  \"publishedAt\": 1786712421975\n}\n\nFile v0.2.17:skill-card.md\n\n## Description:\n\nInstall and use the RunAPI CLI for one-off artifacts and results from registered CLI-backed services.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[runapi-ai](https://clawhub.ai/user/runapi-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent operators use this skill to install, inspect, authenticate, and run supported RunAPI CLI services for one-off tasks, JSON requests, task polling, pricing checks, callback listener workflows, and artifact handling. It directs production application integrations toward the RunAPI SDK instead of guessed CLI commands.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The documented headless installer uses a pipe-to-shell pattern that can create supply-chain exposure if run without review.\n\nMitigation: Prefer the Homebrew install path when available, or download and inspect or verify the installer in a controlled environment before execution.\n\nRisk: API keys, saved login credentials, listener secrets, uploaded files, and webhook listener operations can expose sensitive account or local-service access if handled casually.\n\nMitigation: Provide credentials only intentionally, avoid logging tokens and listener secrets, use stdin or environment auth for API keys, keep listener secrets out of project config, and verify uploads or listener operations before proceeding.\n\nRisk: Installing this skill into other agent runtimes expands where its operational guidance can be invoked.\n\nMitigation: Review the skill and its security guidance before installing it into additional runtimes.\n\n## Reference(s):\n\n- [RunAPI model and CLI catalog](https://runapi.ai/models.md)\n- [RunAPI models homepage](https://runapi.ai/models)\n- [ClawHub skill page](https://clawhub.ai/runapi-ai/skills/runapi-cli)\n- [RunAPI publisher profile](https://clawhub.ai/user/runapi-ai)\n\n## Skill Output:\n\n**Output Type(s):** [guidance, shell commands, configuration, code, text]\n\n**Output Format:** [Markdown with shell commands, JSON examples, and configuration snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Guides agents to inspect installed CLI help before composing requests and to verify generated deliverables before completion.]\n\n## Skill Version(s):\n\n0.2.17 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.2.16: 3 files, 6774 bytes\n\nFiles: skill-card.md (2118b), SKILL.md (13237b), _meta.json (130b)\n\nFile v0.2.16:SKILL.md\n\n---\nname: runapi-cli\ndescription: Install and use the RunAPI CLI for one-off artifacts and results from registered CLI-backed services. Use when the user asks an agent to inspect installed commands, run a supported service, pass JSON request bodies, wait for tasks, or automate a supported RunAPI workflow from the terminal. Use an SDK for app or production integration.\ndocumentation: https://runapi.ai/models.md\ncatalog: https://runapi.ai/models.md\nmetadata:\n  openclaw:\n    homepage: https://runapi.ai/models\n    primaryEnv: RUNAPI_API_KEY\n    requires:\n      bins:\n      - runapi\n    install:\n    - kind: brew\n      formula: runapi-ai/tap/runapi\n      bins:\n      - runapi\n    envVars:\n    - name: RUNAPI_API_KEY\n      required: false\n      description: Optional RunAPI API key; agents should prefer environment auth or saved shared config for headless use. Browser login can be completed with `runapi login` or the MCP `login` tool.\n---\n\n# RunAPI CLI\n\nThe `runapi` CLI executes one-off artifacts or results only for services in its\ninstalled command catalog. An app, backend, worker, library, or production code\nintegration uses a RunAPI SDK instead.\n\n## Choose route\n\nUse the CLI for a one-off artifact or result. Use an SDK for an app, backend,\nworker, library, or production code. Before composing a service command,\ndiscover the installed command catalog with `runapi --help`; proceed only when\nit lists the service. An absent service routes to its SDK or public API contract,\nnot to a guessed CLI command.\n\n## Install\n\n| Target | Command |\n|---|---|\n| macOS / Linux (interactive) | `brew install runapi-ai/tap/runapi` |\n| Server / CI (headless) | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh` |\n| Pin a specific version | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh -s -- --version v0.1.0` |\n\nThe installer detects OS and architecture (Linux and macOS, amd64 and arm64), verifies a SHA-256 checksum from `https://runapi.ai/cli/latest.json`, and refuses to write the binary if verification fails.\n\n## Authentication\n\nCheck the current state first:\n\n```shell\nrunapi auth status\n```\n\n| Source | How |\n|---|---|\n| Environment (agent/headless default) | Read `RUNAPI_API_KEY` from the environment |\n| Saved config (agent/server/CI) | `printf '%s' \"$RUNAPI_API_KEY\" \\| runapi auth import-token --token -` (writes `~/.config/runapi/config.json` with mode 0600) |\n| Browser login (interactive fallback) | `runapi login` in a terminal, or the MCP `login` tool from an MCP host |\n\n`RUNAPI_BASE_URL` overrides the default base URL.\n\nThe RunAPI MCP Server reads the same `~/.config/runapi/config.json` as the CLI. After `runapi login` or the MCP `login` tool completes, authenticated MCP tools can use the saved credentials after the host reloads config if needed.\n\nAvoid `runapi auth import-token --token \"$KEY\"` directly — the value would be visible in `ps -ef` on shared hosts. Use stdin (`--token -`) or `RUNAPI_API_KEY` in the environment.\n\n## Discover services, commands, and fields\n\nThe CLI is JSON-first: every service exposes typed commands, and each command\ndocuments its request fields through `--help`. Always inspect before composing a\nrequest instead of guessing flags.\n\n```shell\nrunapi --help\nrunapi suno --help\nrunapi suno text-to-music --help\n```\n\nSelect capability in order: use `runapi --help` to choose a listed service,\nthen inspect `runapi <service> --help`. Choose `<action>` only from service help,\nthen inspect `runapi <service> <action> --help` for the current request contract,\nincluding nested fields and rules. Use only the listed service, action, model,\nfields, and conditional combinations.\n\n## Run a model\n\nWrite valid JSON to a file and pass it with `--input-file`. The default command\nwaits synchronously and polls until the task completes. Use inline `--input` or\nstdin only when the caller specifically needs that transport.\n\n```shell\n# Synchronous: submit and poll until done\nrunapi suno text-to-music --input-file request.json\n\n# Asynchronous: submit and return immediately, then poll separately\nrunapi suno text-to-music --async --input-file request.json\nrunapi wait <task-id> --service suno --action text-to-music\n\n# Inspect a task without waiting\nrunapi get <task-id> --service suno --action text-to-music\n```\n\nUse `--async` only when the user explicitly requests background execution,\npolling, or webhook integration. Preserve the returned task ID and use the exact\nservice/action pair from the submitted command for `get` or `wait`.\n\nJSON responses go to stdout; progress lines go to stderr. Pipe to `jq` for downstream parsing.\n\n## Account\n\n```shell\nrunapi account info\nrunapi account balance\n```\n\n## Live pricing\n\nPricing commands return current estimates for paid tasks. `pricing list` and\nordinary `pricing quote` calls do not require an API key. A quote with an\nAccount-owned `source_task_id` follows the normal API-key authentication rules.\n\n```shell\nrunapi pricing list --service suno\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params '{\"vocal_mode\":\"auto_lyrics\",\"prompt\":\"A chill lo-fi beat\"}'\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params-file pricing-inputs.json\n```\n\n## Local callback listeners\n\nListener access requires the credential issued by `runapi login`; an ordinary imported API key cannot list callback candidates, read a Listen Signing Secret, or open a listener. This restriction applies only to listener operations: ordinary API keys can still create and query tasks.\n\nBefore running a listener from an agent, check the saved auth and list the current member's key metadata:\n\n```shell\nrunapi auth status\nrunapi api-keys list --json\n```\n\nIf the API returns `cli_listen_required`, explain that the imported key keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override, then complete `runapi login` in their terminal (or the MCP `login` tool) and retry `runapi listen`. Do not retry with an imported API key or a management key.\n\nEach candidate contains `id`, `name`, `masked_token`, and `enabled`. Select an enabled stable `id`; names and masks are display context only, so renaming a key does not invalidate a stored selection. When more than one enabled key is available and the project does not identify one, present the candidates to the user instead of choosing one silently.\n\nSelection precedence is:\n\n1. `--callback-api-key-id <id>` for this invocation. It does not rewrite project config.\n2. `callback_api_key_id` from `.runapi.toml` at the git root, or from the current directory outside a git repository.\n3. The TTY selector. It writes the selected ID only after the server validates the listener session.\n\nNon-TTY invocations never select automatically. Without a flag or config, the `callback_api_key_required` error includes the candidate list so an agent can choose explicitly.\n\nProject config has one allowed field and is safe to commit:\n\n```toml\ncallback_api_key_id = \"token_abc123\"\n```\n\nDo not add credentials, key names, masks, signing secrets, forwarding URLs, or `base_url` to `.runapi.toml`; unknown fields are rejected.\n\nPass the selected ID explicitly from an agent. The listener receives only tasks created with that API key:\n\n```shell\nrunapi listen localhost:3000/webhooks/runapi --callback-api-key-id token_abc123\n```\n\nThe CLI acknowledges each valid listener event before attempting the local HTTP request. It forwards each event locally once and reports non-2xx responses or connection errors without requesting a listener replay. This local debugging behavior does not change delivery retries for a Task's `callback_url`.\n\nEach Account can run up to 100 active listeners per Callback Subscription Key and 1,000 in total. When a limit is reached, stop an idle listener or wait and retry; the response identifies which limit is full. The CLI honors the server's `Retry-After` delay when present. Idle polling checks for events about every 15 to 30 seconds. Events are normally found within about 15 seconds and are read immediately when available.\n\nStartup output identifies the selected key by name, ID, and mask, prints the absolute project config path, and prints that key's stable Listen Signing Secret. To inject the secret without starting a listener, keep it out of logs and project config:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --print-secret --callback-api-key-id token_abc123)\"\n```\n\nIf the secret is exposed, rotate only the selected key's Listen Signing Secret:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --rotate-secret --callback-api-key-id token_abc123)\"\n```\n\nThis invalidates every active listener using the selected key without rotating its business API credential. Update each local verifier with the printed secret, then restart those listeners.\n\nRecovery rules:\n\n- A committed ID owned by another member is not reusable. Run `runapi api-keys list --json`, select that member's key, and pass its ID explicitly. Update the one-line project config only when the project should adopt that member-specific selection.\n- `callback_api_key_unusable` means the selected key was disabled, discarded, or lost membership. The listener exits without falling back; list keys and select another one explicitly.\n- After upgrading from the previous listener behavior, update the CLI, run `runapi login` again, restart listeners, and replace the old local webhook secret.\n\n## Temporary files\n\nPass an agent-readable local path directly to a top-level media URL field. The\nCLI uploads the file before submitting the request and replaces the field value\nwith the temporary URL. Remote `http://` and `https://` values stay unchanged.\n\nUse `runapi files create` only for a reusable URL, Base64 input, or a\ncontract-required upload.\n\n```shell\nrunapi files create ./image.png --file-name image.png\nrunapi files create --url https://cdn.runapi.ai/public/samples/mask.png --file-name image.png\nrunapi files create --base64 \"$BASE64_IMAGE\" --file-name image.png\n```\n\nThe command returns JSON with `file_name`, `url`, `size_bytes`, `mime_type`, `created_at`, and `expires_at`. The returned `url` is a one-hour temporary File Upload URL. Use it in endpoint fields that accept media URLs; check the model/action docs for the exact field name. Add `--url-only` when a script needs only the temporary URL on stdout.\n\n## Install the skill into another agent runtime\n\n```shell\nrunapi agent install-skill --target claude    # ~/.claude/skills/runapi-cli/\nrunapi agent install-skill --target codex     # ~/.codex/skills/runapi-cli/\nrunapi agent install-skill --target gemini    # ~/.gemini/skills/runapi-cli/\nrunapi agent install-skill --target openclaw  # ~/.openclaw/skills/runapi-cli/\nrunapi agent list-targets                     # JSON list with resolved paths\nrunapi agent install-skill --target-dir <path>  # custom location\n```\n\n## Troubleshooting CLI/skill drift\n\nThis skill is installed independently from the `runapi` binary and usually\ntracks the newest CLI behavior. If a command, action, flag, or input field\ndescribed here is unavailable or behaves differently, check the installed CLI\nversion and update it before changing the request:\n\n```shell\nrunapi version\nbrew upgrade runapi-ai/tap/runapi\n# or reinstall\ncurl -fsSL https://runapi.ai/cli/install.sh | sh\n```\n\nAfter updating, inspect the command help again:\n\n```shell\nrunapi --help\nrunapi <service> --help\nrunapi <service> <action> --help\n```\n\n## Safety notes for agents\n\n- Never paste API keys into example commands. Reference `RUNAPI_API_KEY` or `runapi auth import-token` instead.\n- Do not run interactive `runapi login` by default from an agent. In MCP hosts, guide the user through the `login` tool; in terminal/headless contexts, prefer `runapi auth status`, `RUNAPI_API_KEY`, and stdin token import unless the user explicitly wants browser auth.\n- Listener operations are the exception: when they return `cli_listen_required`, an imported key cannot recover. Explain that it keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override and complete browser-backed login; never store the returned credential or Listen Signing Secret in `.runapi.toml`.\n- The CLI exits non-zero on validation failures, network errors, and timeouts. Check the exit code before assuming success.\n- RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.\n\n## Verify, recover, or stop\n\nVerify every requested deliverable: download every URL, require a non-empty\nfile, and check the expected MIME type. A successful task status without the\nrequested files is incomplete.\n\nMake at most one evidence-backed request-shape correction, using the current\ncommand help or a structured validation error. Retry a transient transport\nfailure once only when no task was created, no usage was billed, and replay is\nsafe. Record a terminal service or provider failure and stop without changing\nthe model or action.\n\n## References\n\n- Browse every RunAPI model and its CLI service: https://runapi.ai/models.md\n\nFile v0.2.16:_meta.json\n\n{\n  \"ownerId\": \"kn70me4rk7jqjt92evshjeb5z18768g7\",\n  \"slug\": \"runapi-cli\",\n  \"version\": \"0.2.16\",\n  \"publishedAt\": 1786515922531\n}\n\nFile v0.2.16:skill-card.md\n\n## Description:\n\nInstall and use the RunAPI CLI for one-off artifacts and results from registered CLI-backed services.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[runapi-ai](https://clawhub.ai/user/runapi-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use this skill to inspect installed RunAPI CLI services, submit supported one-off tasks with JSON request bodies, wait for results, and verify returned artifacts. Application and production integrations should use a RunAPI SDK instead of this CLI workflow.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The headless install path pipes a remote installer script into the current shell.\n\nMitigation: Prefer `brew install runapi-ai/tap/runapi` or a verified release artifact; review the installer source before using the curl installer.\n\nRisk: RunAPI API keys, saved credentials, listener signing secrets, and uploaded or generated files are sensitive.\n\nMitigation: Use environment variables or stdin token import for credentials, keep listener secrets out of logs and project config, and store generated deliverables in durable private storage when needed.\n\n## Reference(s):\n\n- [RunAPI model and CLI catalog](https://runapi.ai/models.md)\n- [RunAPI models homepage](https://runapi.ai/models)\n- [ClawHub skill page](https://clawhub.ai/runapi-ai/skills/runapi-cli)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Shell commands, Configuration, JSON]\n\n**Output Format:** [Markdown with inline shell commands and JSON examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Guides agents to inspect current CLI help, use environment or saved authentication, and verify generated files before treating tasks as complete.]\n\n## Skill Version(s):\n\n0.2.16 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.2.15: 3 files, 6542 bytes\n\nFiles: skill-card.md (2630b), SKILL.md (12035b), _meta.json (130b)\n\nFile v0.2.15:SKILL.md\n\n---\nname: runapi-cli\ndescription: Install and use the RunAPI CLI as the universal execution layer for RunAPI models. Use when the user asks to run any RunAPI model from an agent, inspect auth, install RunAPI on a local machine/server/CI, pass JSON request bodies, wait for tasks, or automate RunAPI workflows from the terminal.\ndocumentation: https://runapi.ai/models.md\ncatalog: https://runapi.ai/models.md\nmetadata:\n  openclaw:\n    homepage: https://runapi.ai/models\n    primaryEnv: RUNAPI_API_KEY\n    requires:\n      bins:\n      - runapi\n    install:\n    - kind: brew\n      formula: runapi-ai/tap/runapi\n      bins:\n      - runapi\n    envVars:\n    - name: RUNAPI_API_KEY\n      required: false\n      description: Optional RunAPI API key; agents should prefer environment auth or saved shared config for headless use. Browser login can be completed with `runapi login` or the MCP `login` tool.\n---\n\n# RunAPI CLI\n\nThe `runapi` CLI is the universal execution layer for every RunAPI model that\nships a CLI service. Use it whenever an agent needs to run a one-off model task,\npass a JSON request body, wait for an async task, or script RunAPI from a\nterminal, server, or CI job.\n\n## Install\n\n| Target | Command |\n|---|---|\n| macOS / Linux (interactive) | `brew install runapi-ai/tap/runapi` |\n| Server / CI (headless) | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh` |\n| Pin a specific version | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh -s -- --version v0.1.0` |\n\nThe installer detects OS and architecture (Linux and macOS, amd64 and arm64), verifies a SHA-256 checksum from `https://runapi.ai/cli/latest.json`, and refuses to write the binary if verification fails.\n\n## Authentication\n\nCheck the current state first:\n\n```shell\nrunapi auth status\n```\n\n| Source | How |\n|---|---|\n| Environment (agent/headless default) | Read `RUNAPI_API_KEY` from the environment |\n| Saved config (agent/server/CI) | `printf '%s' \"$RUNAPI_API_KEY\" \\| runapi auth import-token --token -` (writes `~/.config/runapi/config.json` with mode 0600) |\n| Browser login (interactive fallback) | `runapi login` in a terminal, or the MCP `login` tool from an MCP host |\n\n`RUNAPI_BASE_URL` overrides the default base URL.\n\nThe RunAPI MCP Server reads the same `~/.config/runapi/config.json` as the CLI. After `runapi login` or the MCP `login` tool completes, authenticated MCP tools can use the saved credentials after the host reloads config if needed.\n\nAvoid `runapi auth import-token --token \"$KEY\"` directly — the value would be visible in `ps -ef` on shared hosts. Use stdin (`--token -`) or `RUNAPI_API_KEY` in the environment.\n\n## Discover services, commands, and fields\n\nThe CLI is JSON-first: every service exposes typed commands, and each command\ndocuments its request fields through `--help`. Always inspect before composing a\nrequest instead of guessing flags.\n\n```shell\nrunapi --help\nrunapi suno --help\nrunapi suno text-to-music --help\n```\n\n## Run a model\n\nPass the request body as JSON through `--input-file` (or `--input` for inline\nJSON, or `-` for stdin). The default flow is synchronous and polls until the\ntask completes.\n\n```shell\n# Synchronous: submit and poll until done\nrunapi suno text-to-music --input-file request.json\n\n# Asynchronous: submit and return immediately, then poll separately\nrunapi suno text-to-music --async --input-file request.json\nrunapi wait <task-id> --service suno --action text-to-music\n\n# Inspect a task without waiting\nrunapi get <task-id> --service suno --action text-to-music\n```\n\nJSON responses go to stdout; progress lines go to stderr. Pipe to `jq` for downstream parsing.\n\n## Account\n\n```shell\nrunapi account info\nrunapi account balance\n```\n\n## Live pricing\n\nPricing commands return current estimates for paid tasks. `pricing list` and\nordinary `pricing quote` calls do not require an API key. A quote with an\nAccount-owned `source_task_id` follows the normal API-key authentication rules.\n\n```shell\nrunapi pricing list --service suno\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params '{\"vocal_mode\":\"auto_lyrics\",\"prompt\":\"A chill lo-fi beat\"}'\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params-file pricing-inputs.json\n```\n\n## Local callback listeners\n\nListener access requires the credential issued by `runapi login`; an ordinary imported API key cannot list callback candidates, read a Listen Signing Secret, or open a listener. This restriction applies only to listener operations: ordinary API keys can still create and query tasks.\n\nBefore running a listener from an agent, check the saved auth and list the current member's key metadata:\n\n```shell\nrunapi auth status\nrunapi api-keys list --json\n```\n\nIf the API returns `cli_listen_required`, explain that the imported key keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override, then complete `runapi login` in their terminal (or the MCP `login` tool) and retry `runapi listen`. Do not retry with an imported API key or a management key.\n\nEach candidate contains `id`, `name`, `masked_token`, and `enabled`. Select an enabled stable `id`; names and masks are display context only, so renaming a key does not invalidate a stored selection. When more than one enabled key is available and the project does not identify one, present the candidates to the user instead of choosing one silently.\n\nSelection precedence is:\n\n1. `--callback-api-key-id <id>` for this invocation. It does not rewrite project config.\n2. `callback_api_key_id` from `.runapi.toml` at the git root, or from the current directory outside a git repository.\n3. The TTY selector. It writes the selected ID only after the server validates the listener session.\n\nNon-TTY invocations never select automatically. Without a flag or config, the `callback_api_key_required` error includes the candidate list so an agent can choose explicitly.\n\nProject config has one allowed field and is safe to commit:\n\n```toml\ncallback_api_key_id = \"token_abc123\"\n```\n\nDo not add credentials, key names, masks, signing secrets, forwarding URLs, or `base_url` to `.runapi.toml`; unknown fields are rejected.\n\nPass the selected ID explicitly from an agent. The listener receives only tasks created with that API key:\n\n```shell\nrunapi listen localhost:3000/webhooks/runapi --callback-api-key-id token_abc123\n```\n\nThe CLI acknowledges each valid listener event before attempting the local HTTP request. It forwards each event locally once and reports non-2xx responses or connection errors without requesting a listener replay. This local debugging behavior does not change delivery retries for a Task's `callback_url`.\n\nEach Account can run up to 100 active listeners per Callback Subscription Key and 1,000 in total. When a limit is reached, stop an idle listener or wait and retry; the response identifies which limit is full. The CLI honors the server's `Retry-After` delay when present. Idle polling checks for events about every 15 to 30 seconds. Events are normally found within about 15 seconds and are read immediately when available.\n\nStartup output identifies the selected key by name, ID, and mask, prints the absolute project config path, and prints that key's stable Listen Signing Secret. To inject the secret without starting a listener, keep it out of logs and project config:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --print-secret --callback-api-key-id token_abc123)\"\n```\n\nIf the secret is exposed, rotate only the selected key's Listen Signing Secret:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --rotate-secret --callback-api-key-id token_abc123)\"\n```\n\nThis invalidates every active listener using the selected key without rotating its business API credential. Update each local verifier with the printed secret, then restart those listeners.\n\nRecovery rules:\n\n- A committed ID owned by another member is not reusable. Run `runapi api-keys list --json`, select that member's key, and pass its ID explicitly. Update the one-line project config only when the project should adopt that member-specific selection.\n- `callback_api_key_unusable` means the selected key was disabled, discarded, or lost membership. The listener exits without falling back; list keys and select another one explicitly.\n- After upgrading from the previous listener behavior, update the CLI, run `runapi login` again, restart listeners, and replace the old local webhook secret.\n\n## Temporary files\n\nModel commands accept readable local file paths in top-level media URL fields, such as `source_image_url`, `source_image_urls`, `reference_image_urls`, `first_frame_image_url`, `mask_url`, `upload_url`, or `source_audio_url`. The CLI uploads each local file before submitting the request and replaces the field value with the temporary URL. Remote `http://` and `https://` values stay unchanged.\n\nUse `runapi files create` when you need an explicit temporary URL for reuse, or when the source is Base64 encoded or already hosted at another URL.\n\n```shell\nrunapi files create ./image.png --file-name image.png\nrunapi files create --url https://cdn.runapi.ai/public/samples/mask.png --file-name image.png\nrunapi files create --base64 \"$BASE64_IMAGE\" --file-name image.png\n```\n\nThe command returns JSON with `file_name`, `url`, `size_bytes`, `mime_type`, `created_at`, and `expires_at`. The returned `url` is a one-hour temporary File Upload URL. Use it in endpoint fields that accept media URLs; check the model/action docs for the exact field name. Add `--url-only` when a script needs only the temporary URL on stdout.\n\n## Install the skill into another agent runtime\n\n```shell\nrunapi agent install-skill --target claude    # ~/.claude/skills/runapi-cli/\nrunapi agent install-skill --target codex     # ~/.codex/skills/runapi-cli/\nrunapi agent install-skill --target gemini    # ~/.gemini/skills/runapi-cli/\nrunapi agent install-skill --target openclaw  # ~/.openclaw/skills/runapi-cli/\nrunapi agent list-targets                     # JSON list with resolved paths\nrunapi agent install-skill --target-dir <path>  # custom location\n```\n\n## Troubleshooting CLI/skill drift\n\nThis skill is installed independently from the `runapi` binary and usually\ntracks the newest CLI behavior. If a command, action, flag, or input field\ndescribed here is unavailable or behaves differently, check the installed CLI\nversion and update it before changing the request:\n\n```shell\nrunapi version\nbrew upgrade runapi-ai/tap/runapi\n# or reinstall\ncurl -fsSL https://runapi.ai/cli/install.sh | sh\n```\n\nAfter updating, inspect the command help again:\n\n```shell\nrunapi --help\nrunapi <service> --help\nrunapi <service> <action> --help\n```\n\n## Safety notes for agents\n\n- Never paste API keys into example commands. Reference `RUNAPI_API_KEY` or `runapi auth import-token` instead.\n- Do not run interactive `runapi login` by default from an agent. In MCP hosts, guide the user through the `login` tool; in terminal/headless contexts, prefer `runapi auth status`, `RUNAPI_API_KEY`, and stdin token import unless the user explicitly wants browser auth.\n- Listener operations are the exception: when they return `cli_listen_required`, an imported key cannot recover. Explain that it keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override and complete browser-backed login; never store the returned credential or Listen Signing Secret in `.runapi.toml`.\n- The CLI exits non-zero on validation failures, network errors, and timeouts. Check the exit code before assuming success.\n- For long-running tasks, prefer `--async` plus a `wait` loop so the agent can release the shell promptly.\n- RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.\n\n## References\n\n- Browse every RunAPI model and its CLI service: https://runapi.ai/models.md\n\nFile v0.2.15:_meta.json\n\n{\n  \"ownerId\": \"kn70me4rk7jqjt92evshjeb5z18768g7\",\n  \"slug\": \"runapi-cli\",\n  \"version\": \"0.2.15\",\n  \"publishedAt\": 1786371195241\n}\n\nFile v0.2.15:skill-card.md\n\n## Description:\n\nInstall and use the RunAPI CLI as the universal execution layer for RunAPI models. Use when the user asks to run any RunAPI model from an agent, inspect auth, install RunAPI on a local machine/server/CI, pass JSON request bodies, wait for tasks, or automate RunAPI workflows from the terminal.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[runapi-ai](https://clawhub.ai/user/runapi-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use this skill to install, authenticate, inspect, and run RunAPI model workflows from terminal, server, CI, or agent runtimes. It supports JSON-first model execution, task polling, pricing checks, file uploads, callback listener setup, and troubleshooting CLI or skill drift.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Installing through a curl-to-sh command can execute remote installer code in the target environment.\n\nMitigation: Prefer the Homebrew install path when available; use the curl installer only where the RunAPI installer source is trusted.\n\nRisk: API keys or listener secrets can be exposed through command arguments, logs, or committed configuration.\n\nMitigation: Use RUNAPI_API_KEY or stdin token import, keep credentials scoped, and do not commit webhook secrets or credentials.\n\nRisk: Listener operations require browser-backed CLI credentials and may fail or select the wrong callback key if account state is not checked first.\n\nMitigation: Verify the active account and list API key metadata before listener use; pass an enabled callback API key ID explicitly when needed.\n\n## Reference(s):\n\n- [RunAPI model and CLI service catalog](https://runapi.ai/models.md)\n- [RunAPI models homepage](https://runapi.ai/models)\n- [ClawHub skill page](https://clawhub.ai/runapi-ai/skills/runapi-cli)\n- [Publisher profile](https://clawhub.ai/user/runapi-ai)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands, JSON examples, and configuration snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Guidance may reference RUNAPI_API_KEY, local config files, temporary file URLs, and command exit status handling.]\n\n## Skill Version(s):\n\n0.2.15 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.2.14: 3 files, 6547 bytes\n\nFiles: skill-card.md (2729b), SKILL.md (12035b), _meta.json (130b)\n\nFile v0.2.14:SKILL.md\n\n---\nname: runapi-cli\ndescription: Install and use the RunAPI CLI as the universal execution layer for RunAPI models. Use when the user asks to run any RunAPI model from an agent, inspect auth, install RunAPI on a local machine/server/CI, pass JSON request bodies, wait for tasks, or automate RunAPI workflows from the terminal.\ndocumentation: https://runapi.ai/models.md\ncatalog: https://runapi.ai/models.md\nmetadata:\n  openclaw:\n    homepage: https://runapi.ai/models\n    primaryEnv: RUNAPI_API_KEY\n    requires:\n      bins:\n      - runapi\n    install:\n    - kind: brew\n      formula: runapi-ai/tap/runapi\n      bins:\n      - runapi\n    envVars:\n    - name: RUNAPI_API_KEY\n      required: false\n      description: Optional RunAPI API key; agents should prefer environment auth or saved shared config for headless use. Browser login can be completed with `runapi login` or the MCP `login` tool.\n---\n\n# RunAPI CLI\n\nThe `runapi` CLI is the universal execution layer for every RunAPI model that\nships a CLI service. Use it whenever an agent needs to run a one-off model task,\npass a JSON request body, wait for an async task, or script RunAPI from a\nterminal, server, or CI job.\n\n## Install\n\n| Target | Command |\n|---|---|\n| macOS / Linux (interactive) | `brew install runapi-ai/tap/runapi` |\n| Server / CI (headless) | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh` |\n| Pin a specific version | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh -s -- --version v0.1.0` |\n\nThe installer detects OS and architecture (Linux and macOS, amd64 and arm64), verifies a SHA-256 checksum from `https://runapi.ai/cli/latest.json`, and refuses to write the binary if verification fails.\n\n## Authentication\n\nCheck the current state first:\n\n```shell\nrunapi auth status\n```\n\n| Source | How |\n|---|---|\n| Environment (agent/headless default) | Read `RUNAPI_API_KEY` from the environment |\n| Saved config (agent/server/CI) | `printf '%s' \"$RUNAPI_API_KEY\" \\| runapi auth import-token --token -` (writes `~/.config/runapi/config.json` with mode 0600) |\n| Browser login (interactive fallback) | `runapi login` in a terminal, or the MCP `login` tool from an MCP host |\n\n`RUNAPI_BASE_URL` overrides the default base URL.\n\nThe RunAPI MCP Server reads the same `~/.config/runapi/config.json` as the CLI. After `runapi login` or the MCP `login` tool completes, authenticated MCP tools can use the saved credentials after the host reloads config if needed.\n\nAvoid `runapi auth import-token --token \"$KEY\"` directly — the value would be visible in `ps -ef` on shared hosts. Use stdin (`--token -`) or `RUNAPI_API_KEY` in the environment.\n\n## Discover services, commands, and fields\n\nThe CLI is JSON-first: every service exposes typed commands, and each command\ndocuments its request fields through `--help`. Always inspect before composing a\nrequest instead of guessing flags.\n\n```shell\nrunapi --help\nrunapi suno --help\nrunapi suno text-to-music --help\n```\n\n## Run a model\n\nPass the request body as JSON through `--input-file` (or `--input` for inline\nJSON, or `-` for stdin). The default flow is synchronous and polls until the\ntask completes.\n\n```shell\n# Synchronous: submit and poll until done\nrunapi suno text-to-music --input-file request.json\n\n# Asynchronous: submit and return immediately, then poll separately\nrunapi suno text-to-music --async --input-file request.json\nrunapi wait <task-id> --service suno --action text-to-music\n\n# Inspect a task without waiting\nrunapi get <task-id> --service suno --action text-to-music\n```\n\nJSON responses go to stdout; progress lines go to stderr. Pipe to `jq` for downstream parsing.\n\n## Account\n\n```shell\nrunapi account info\nrunapi account balance\n```\n\n## Live pricing\n\nPricing commands return current estimates for paid tasks. `pricing list` and\nordinary `pricing quote` calls do not require an API key. A quote with an\nAccount-owned `source_task_id` follows the normal API-key authentication rules.\n\n```shell\nrunapi pricing list --service suno\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params '{\"vocal_mode\":\"auto_lyrics\",\"prompt\":\"A chill lo-fi beat\"}'\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params-file pricing-inputs.json\n```\n\n## Local callback listeners\n\nListener access requires the credential issued by `runapi login`; an ordinary imported API key cannot list callback candidates, read a Listen Signing Secret, or open a listener. This restriction applies only to listener operations: ordinary API keys can still create and query tasks.\n\nBefore running a listener from an agent, check the saved auth and list the current member's key metadata:\n\n```shell\nrunapi auth status\nrunapi api-keys list --json\n```\n\nIf the API returns `cli_listen_required`, explain that the imported key keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override, then complete `runapi login` in their terminal (or the MCP `login` tool) and retry `runapi listen`. Do not retry with an imported API key or a management key.\n\nEach candidate contains `id`, `name`, `masked_token`, and `enabled`. Select an enabled stable `id`; names and masks are display context only, so renaming a key does not invalidate a stored selection. When more than one enabled key is available and the project does not identify one, present the candidates to the user instead of choosing one silently.\n\nSelection precedence is:\n\n1. `--callback-api-key-id <id>` for this invocation. It does not rewrite project config.\n2. `callback_api_key_id` from `.runapi.toml` at the git root, or from the current directory outside a git repository.\n3. The TTY selector. It writes the selected ID only after the server validates the listener session.\n\nNon-TTY invocations never select automatically. Without a flag or config, the `callback_api_key_required` error includes the candidate list so an agent can choose explicitly.\n\nProject config has one allowed field and is safe to commit:\n\n```toml\ncallback_api_key_id = \"token_abc123\"\n```\n\nDo not add credentials, key names, masks, signing secrets, forwarding URLs, or `base_url` to `.runapi.toml`; unknown fields are rejected.\n\nPass the selected ID explicitly from an agent. The listener receives only tasks created with that API key:\n\n```shell\nrunapi listen localhost:3000/webhooks/runapi --callback-api-key-id token_abc123\n```\n\nThe CLI acknowledges each valid listener event before attempting the local HTTP request. It forwards each event locally once and reports non-2xx responses or connection errors without requesting a listener replay. This local debugging behavior does not change delivery retries for a Task's `callback_url`.\n\nEach Account can run up to 100 active listeners per Callback Subscription Key and 1,000 in total. When a limit is reached, stop an idle listener or wait and retry; the response identifies which limit is full. The CLI honors the server's `Retry-After` delay when present. Idle polling checks for events about every 15 to 30 seconds. Events are normally found within about 15 seconds and are read immediately when available.\n\nStartup output identifies the selected key by name, ID, and mask, prints the absolute project config path, and prints that key's stable Listen Signing Secret. To inject the secret without starting a listener, keep it out of logs and project config:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --print-secret --callback-api-key-id token_abc123)\"\n```\n\nIf the secret is exposed, rotate only the selected key's Listen Signing Secret:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --rotate-secret --callback-api-key-id token_abc123)\"\n```\n\nThis invalidates every active listener using the selected key without rotating its business API credential. Update each local verifier with the printed secret, then restart those listeners.\n\nRecovery rules:\n\n- A committed ID owned by another member is not reusable. Run `runapi api-keys list --json`, select that member's key, and pass its ID explicitly. Update the one-line project config only when the project should adopt that member-specific selection.\n- `callback_api_key_unusable` means the selected key was disabled, discarded, or lost membership. The listener exits without falling back; list keys and select another one explicitly.\n- After upgrading from the previous listener behavior, update the CLI, run `runapi login` again, restart listeners, and replace the old local webhook secret.\n\n## Temporary files\n\nModel commands accept readable local file paths in top-level media URL fields, such as `source_image_url`, `source_image_urls`, `reference_image_urls`, `first_frame_image_url`, `mask_url`, `upload_url`, or `source_audio_url`. The CLI uploads each local file before submitting the request and replaces the field value with the temporary URL. Remote `http://` and `https://` values stay unchanged.\n\nUse `runapi files create` when you need an explicit temporary URL for reuse, or when the source is Base64 encoded or already hosted at another URL.\n\n```shell\nrunapi files create ./image.png --file-name image.png\nrunapi files create --url https://cdn.runapi.ai/public/samples/mask.png --file-name image.png\nrunapi files create --base64 \"$BASE64_IMAGE\" --file-name image.png\n```\n\nThe command returns JSON with `file_name`, `url`, `size_bytes`, `mime_type`, `created_at`, and `expires_at`. The returned `url` is a one-hour temporary File Upload URL. Use it in endpoint fields that accept media URLs; check the model/action docs for the exact field name. Add `--url-only` when a script needs only the temporary URL on stdout.\n\n## Install the skill into another agent runtime\n\n```shell\nrunapi agent install-skill --target claude    # ~/.claude/skills/runapi-cli/\nrunapi agent install-skill --target codex     # ~/.codex/skills/runapi-cli/\nrunapi agent install-skill --target gemini    # ~/.gemini/skills/runapi-cli/\nrunapi agent install-skill --target openclaw  # ~/.openclaw/skills/runapi-cli/\nrunapi agent list-targets                     # JSON list with resolved paths\nrunapi agent install-skill --target-dir <path>  # custom location\n```\n\n## Troubleshooting CLI/skill drift\n\nThis skill is installed independently from the `runapi` binary and usually\ntracks the newest CLI behavior. If a command, action, flag, or input field\ndescribed here is unavailable or behaves differently, check the installed CLI\nversion and update it before changing the request:\n\n```shell\nrunapi version\nbrew upgrade runapi-ai/tap/runapi\n# or reinstall\ncurl -fsSL https://runapi.ai/cli/install.sh | sh\n```\n\nAfter updating, inspect the command help again:\n\n```shell\nrunapi --help\nrunapi <service> --help\nrunapi <service> <action> --help\n```\n\n## Safety notes for agents\n\n- Never paste API keys into example commands. Reference `RUNAPI_API_KEY` or `runapi auth import-token` instead.\n- Do not run interactive `runapi login` by default from an agent. In MCP hosts, guide the user through the `login` tool; in terminal/headless contexts, prefer `runapi auth status`, `RUNAPI_API_KEY`, and stdin token import unless the user explicitly wants browser auth.\n- Listener operations are the exception: when they return `cli_listen_required`, an imported key cannot recover. Explain that it keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override and complete browser-backed login; never store the returned credential or Listen Signing Secret in `.runapi.toml`.\n- The CLI exits non-zero on validation failures, network errors, and timeouts. Check the exit code before assuming success.\n- For long-running tasks, prefer `--async` plus a `wait` loop so the agent can release the shell promptly.\n- RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.\n\n## References\n\n- Browse every RunAPI model and its CLI service: https://runapi.ai/models.md\n\nFile v0.2.14:_meta.json\n\n{\n  \"ownerId\": \"kn70me4rk7jqjt92evshjeb5z18768g7\",\n  \"slug\": \"runapi-cli\",\n  \"version\": \"0.2.14\",\n  \"publishedAt\": 1785860856636\n}\n\nFile v0.2.14:skill-card.md\n\n## Description: <br>\nInstall and use the RunAPI CLI as the universal execution layer for RunAPI models when an agent needs to run model tasks, inspect auth, install RunAPI, pass JSON request bodies, wait for tasks, or automate workflows from the terminal. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[runapi-ai](https://clawhub.ai/user/runapi-ai) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers, engineers, and agent operators use this skill to install, authenticate, inspect, and run RunAPI model workflows from terminals, servers, CI jobs, or supported agent runtimes. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The curl-based installer can introduce supply-chain risk if used without review or artifact verification. <br>\nMitigation: Prefer the Homebrew installation path when available; for CI or server installs, review the fetched script first or pin and verify the release artifact independently. <br>\nRisk: RunAPI credentials, callback signing secrets, and uploaded local media can be sensitive. <br>\nMitigation: Use environment variables or stdin for API keys, avoid logging listener secrets, keep credentials out of project config, and treat uploaded media URLs as temporary sensitive artifacts. <br>\nRisk: Listener and cross-agent install commands can affect local services or other agent runtimes. <br>\nMitigation: Run listener or cross-agent install commands only when the workflow intentionally needs them, and select listener callback API key IDs explicitly in non-interactive contexts. <br>\n\n\n## Reference(s): <br>\n- [RunAPI model catalog and CLI documentation](https://runapi.ai/models.md) <br>\n- [RunAPI models homepage](https://runapi.ai/models) <br>\n- [ClawHub runapi-cli skill page](https://clawhub.ai/runapi-ai/skills/runapi-cli) <br>\n- [ClawHub runapi-ai publisher profile](https://clawhub.ai/user/runapi-ai) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance] <br>\n**Output Format:** [Markdown guidance with inline shell commands, JSON examples, and TOML configuration snippets] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Commands may produce JSON on stdout and progress or error messages on stderr when executed by the agent.] <br>\n\n## Skill Version(s): <br>\n0.2.14 (source: evidence.release.version) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v0.2.13: 3 files, 6462 bytes\n\nFiles: skill-card.md (2996b), SKILL.md (11611b), _meta.json (130b)\n\nFile v0.2.13:SKILL.md\n\n---\nname: runapi-cli\ndescription: Install and use the RunAPI CLI as the universal execution layer for RunAPI models. Use when the user asks to run any RunAPI model from an agent, inspect auth, install RunAPI on a local machine/server/CI, pass JSON request bodies, wait for tasks, or automate RunAPI workflows from the terminal.\ndocumentation: https://runapi.ai/models.md\ncatalog: https://runapi.ai/models.md\nmetadata:\n  openclaw:\n    homepage: https://runapi.ai/models\n    primaryEnv: RUNAPI_API_KEY\n    requires:\n      bins:\n      - runapi\n    install:\n    - kind: brew\n      formula: runapi-ai/tap/runapi\n      bins:\n      - runapi\n    envVars:\n    - name: RUNAPI_API_KEY\n      required: false\n      description: Optional RunAPI API key; agents should prefer environment auth or saved shared config for headless use. Browser login can be completed with `runapi login` or the MCP `login` tool.\n---\n\n# RunAPI CLI\n\nThe `runapi` CLI is the universal execution layer for every RunAPI model that\nships a CLI service. Use it whenever an agent needs to run a one-off model task,\npass a JSON request body, wait for an async task, or script RunAPI from a\nterminal, server, or CI job.\n\n## Install\n\n| Target | Command |\n|---|---|\n| macOS / Linux (interactive) | `brew install runapi-ai/tap/runapi` |\n| Server / CI (headless) | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh` |\n| Pin a specific version | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh -s -- --version v0.1.0` |\n\nThe installer detects OS and architecture (Linux and macOS, amd64 and arm64), verifies a SHA-256 checksum from `https://runapi.ai/cli/latest.json`, and refuses to write the binary if verification fails.\n\n## Authentication\n\nCheck the current state first:\n\n```shell\nrunapi auth status\n```\n\n| Source | How |\n|---|---|\n| Environment (agent/headless default) | Read `RUNAPI_API_KEY` from the environment |\n| Saved config (agent/server/CI) | `printf '%s' \"$RUNAPI_API_KEY\" \\| runapi auth import-token --token -` (writes `~/.config/runapi/config.json` with mode 0600) |\n| Browser login (interactive fallback) | `runapi login` in a terminal, or the MCP `login` tool from an MCP host |\n\n`RUNAPI_BASE_URL` overrides the default base URL.\n\nThe RunAPI MCP Server reads the same `~/.config/runapi/config.json` as the CLI. After `runapi login` or the MCP `login` tool completes, authenticated MCP tools can use the saved credentials after the host reloads config if needed.\n\nAvoid `runapi auth import-token --token \"$KEY\"` directly — the value would be visible in `ps -ef` on shared hosts. Use stdin (`--token -`) or `RUNAPI_API_KEY` in the environment.\n\n## Discover services, commands, and fields\n\nThe CLI is JSON-first: every service exposes typed commands, and each command\ndocuments its request fields through `--help`. Always inspect before composing a\nrequest instead of guessing flags.\n\n```shell\nrunapi --help\nrunapi suno --help\nrunapi suno text-to-music --help\n```\n\n## Run a model\n\nPass the request body as JSON through `--input-file` (or `--input` for inline\nJSON, or `-` for stdin). The default flow is synchronous and polls until the\ntask completes.\n\n```shell\n# Synchronous: submit and poll until done\nrunapi suno text-to-music --input-file request.json\n\n# Asynchronous: submit and return immediately, then poll separately\nrunapi suno text-to-music --async --input-file request.json\nrunapi wait <task-id> --service suno --action text-to-music\n\n# Inspect a task without waiting\nrunapi get <task-id> --service suno --action text-to-music\n```\n\nJSON responses go to stdout; progress lines go to stderr. Pipe to `jq` for downstream parsing.\n\n## Account\n\n```shell\nrunapi account info\nrunapi account balance\n```\n\n## Live pricing\n\nPricing commands return current estimates for paid tasks. `pricing list` and\nordinary `pricing quote` calls do not require an API key. A quote with an\nAccount-owned `source_task_id` follows the normal API-key authentication rules.\n\n```shell\nrunapi pricing list --service suno\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params '{\"vocal_mode\":\"auto_lyrics\",\"prompt\":\"A chill lo-fi beat\"}'\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params-file pricing-inputs.json\n```\n\n## Local callback listeners\n\nListener access requires the credential issued by `runapi login`; an ordinary imported API key cannot list callback candidates, read a Listen Signing Secret, or open a listener. This restriction applies only to listener operations: ordinary API keys can still create and query tasks.\n\nBefore running a listener from an agent, check the saved auth and list the current member's key metadata:\n\n```shell\nrunapi auth status\nrunapi api-keys list --json\n```\n\nIf the API returns `cli_listen_required`, explain that the imported key keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override, then complete `runapi login` in their terminal (or the MCP `login` tool) and retry `runapi listen`. Do not retry with an imported API key or a management key.\n\nEach candidate contains `id`, `name`, `masked_token`, and `enabled`. Select an enabled stable `id`; names and masks are display context only, so renaming a key does not invalidate a stored selection. When more than one enabled key is available and the project does not identify one, present the candidates to the user instead of choosing one silently.\n\nSelection precedence is:\n\n1. `--callback-api-key-id <id>` for this invocation. It does not rewrite project config.\n2. `callback_api_key_id` from `.runapi.toml` at the git root, or from the current directory outside a git repository.\n3. The TTY selector. It writes the selected ID only after the server validates the listener session.\n\nNon-TTY invocations never select automatically. Without a flag or config, the `callback_api_key_required` error includes the candidate list so an agent can choose explicitly.\n\nProject config has one allowed field and is safe to commit:\n\n```toml\ncallback_api_key_id = \"token_abc123\"\n```\n\nDo not add credentials, key names, masks, signing secrets, forwarding URLs, or `base_url` to `.runapi.toml`; unknown fields are rejected.\n\nPass the selected ID explicitly from an agent. The listener receives only tasks created with that API key:\n\n```shell\nrunapi listen localhost:3000/webhooks/runapi --callback-api-key-id token_abc123\n```\n\nThe CLI acknowledges each valid listener event before attempting the local HTTP request. It forwards each event locally once and reports non-2xx responses or connection errors without requesting a listener replay. This local debugging behavior does not change delivery retries for a Task's `callback_url`.\n\nStartup output identifies the selected key by name, ID, and mask, prints the absolute project config path, and prints that key's stable Listen Signing Secret. To inject the secret without starting a listener, keep it out of logs and project config:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --print-secret --callback-api-key-id token_abc123)\"\n```\n\nIf the secret is exposed, rotate only the selected key's Listen Signing Secret:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --rotate-secret --callback-api-key-id token_abc123)\"\n```\n\nThis invalidates every active listener using the selected key without rotating its business API credential. Update each local verifier with the printed secret, then restart those listeners.\n\nRecovery rules:\n\n- A committed ID owned by another member is not reusable. Run `runapi api-keys list --json`, select that member's key, and pass its ID explicitly. Update the one-line project config only when the project should adopt that member-specific selection.\n- `callback_api_key_unusable` means the selected key was disabled, discarded, or lost membership. The listener exits without falling back; list keys and select another one explicitly.\n- After upgrading from the previous listener behavior, update the CLI, run `runapi login` again, restart listeners, and replace the old local webhook secret.\n\n## Temporary files\n\nModel commands accept readable local file paths in top-level media URL fields, such as `source_image_url`, `source_image_urls`, `reference_image_urls`, `first_frame_image_url`, `mask_url`, `upload_url`, or `source_audio_url`. The CLI uploads each local file before submitting the request and replaces the field value with the temporary URL. Remote `http://` and `https://` values stay unchanged.\n\nUse `runapi files create` when you need an explicit temporary URL for reuse, or when the source is Base64 encoded or already hosted at another URL.\n\n```shell\nrunapi files create ./image.png --file-name image.png\nrunapi files create --url https://cdn.runapi.ai/public/samples/mask.png --file-name image.png\nrunapi files create --base64 \"$BASE64_IMAGE\" --file-name image.png\n```\n\nThe command returns JSON with `file_name`, `url`, `size_bytes`, `mime_type`, `created_at`, and `expires_at`. The returned `url` is a one-hour temporary File Upload URL. Use it in endpoint fields that accept media URLs; check the model/action docs for the exact field name. Add `--url-only` when a script needs only the temporary URL on stdout.\n\n## Install the skill into another agent runtime\n\n```shell\nrunapi agent install-skill --target claude    # ~/.claude/skills/runapi-cli/\nrunapi agent install-skill --target codex     # ~/.codex/skills/runapi-cli/\nrunapi agent install-skill --target gemini    # ~/.gemini/skills/runapi-cli/\nrunapi agent install-skill --target openclaw  # ~/.openclaw/skills/runapi-cli/\nrunapi agent list-targets                     # JSON list with resolved paths\nrunapi agent install-skill --target-dir <path>  # custom location\n```\n\n## Troubleshooting CLI/skill drift\n\nThis skill is installed independently from the `runapi` binary and usually\ntracks the newest CLI behavior. If a command, action, flag, or input field\ndescribed here is unavailable or behaves differently, check the installed CLI\nversion and update it before changing the request:\n\n```shell\nrunapi version\nbrew upgrade runapi-ai/tap/runapi\n# or reinstall\ncurl -fsSL https://runapi.ai/cli/install.sh | sh\n```\n\nAfter updating, inspect the command help again:\n\n```shell\nrunapi --help\nrunapi <service> --help\nrunapi <service> <action> --help\n```\n\n## Safety notes for agents\n\n- Never paste API keys into example commands. Reference `RUNAPI_API_KEY` or `runapi auth import-token` instead.\n- Do not run interactive `runapi login` by default from an agent. In MCP hosts, guide the user through the `login` tool; in terminal/headless contexts, prefer `runapi auth status`, `RUNAPI_API_KEY`, and stdin token import unless the user explicitly wants browser auth.\n- Listener operations are the exception: when they return `cli_listen_required`, an imported key cannot recover. Explain that it keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override and complete browser-backed login; never store the returned credential or Listen Signing Secret in `.runapi.toml`.\n- The CLI exits non-zero on validation failures, network errors, and timeouts. Check the exit code before assuming success.\n- For long-running tasks, prefer `--async` plus a `wait` loop so the agent can release the shell promptly.\n- RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.\n\n## References\n\n- Browse every RunAPI model and its CLI service: https://runapi.ai/models.md\n\nFile v0.2.13:_meta.json\n\n{\n  \"ownerId\": \"kn70me4rk7jqjt92evshjeb5z18768g7\",\n  \"slug\": \"runapi-cli\",\n  \"version\": \"0.2.13\",\n  \"publishedAt\": 1785491746333\n}\n\nFile v0.2.13:skill-card.md\n\n## Description: <br>\nInstall and use the RunAPI CLI as the universal execution layer for RunAPI models. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[runapi-ai](https://clawhub.ai/user/runapi-ai) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers, engineers, and agent operators use this skill to install, authenticate, inspect, and automate RunAPI CLI workflows from terminals, servers, CI jobs, and agent runtimes. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Installer scripts and binary installation flows can affect the local system if sourced from the wrong place or tampered with. <br>\nMitigation: Prefer the Homebrew install path or a verified installer flow, and rely on the documented checksum verification before using the installed runapi binary. <br>\nRisk: RunAPI API keys, saved credentials, and listener signing secrets could be exposed through shared environments, process arguments, logs, or committed config files. <br>\nMitigation: Use RUNAPI_API_KEY or stdin token import instead of command-line token arguments, keep credentials out of project config and repositories, and rotate listener signing secrets if exposed. <br>\nRisk: Local files passed to RunAPI upload fields may contain sensitive or unintended content. <br>\nMitigation: Review local files before passing paths to upload fields and treat returned temporary URLs as short-lived transfer artifacts rather than durable storage. <br>\nRisk: Local callback listener failures can be missed because each valid event is acknowledged before the local HTTP forward attempt and forwarded locally once. <br>\nMitigation: Monitor non-2xx responses or connection errors, check CLI exit status, and debug local webhook handling without assuming a listener replay will occur. <br>\n\n\n## Reference(s): <br>\n- [RunAPI model and CLI service catalog](https://runapi.ai/models.md) <br>\n- [RunAPI model browser](https://runapi.ai/models) <br>\n- [ClawHub runapi-cli skill page](https://clawhub.ai/runapi-ai/skills/runapi-cli) <br>\n- [ClawHub runapi-ai publisher profile](https://clawhub.ai/user/runapi-ai) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Guidance, Shell commands, Configuration, Code, JSON] <br>\n**Output Format:** [Markdown guidance with shell commands, JSON examples, and configuration snippets] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Guidance covers RunAPI CLI installation, authentication, model execution, pricing, callback listeners, temporary file uploads, and agent-runtime skill installation.] <br>\n\n## Skill Version(s): <br>\n0.2.13 (source: server release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v0.2.12: 3 files, 5999 bytes\n\nFiles: skill-card.md (2148b), SKILL.md (11304b), _meta.json (130b)\n\nFile v0.2.12:SKILL.md\n\n---\nname: runapi-cli\ndescription: Install and use the RunAPI CLI as the universal execution layer for RunAPI models. Use when the user asks to run any RunAPI model from an agent, inspect auth, install RunAPI on a local machine/server/CI, pass JSON request bodies, wait for tasks, or automate RunAPI workflows from the terminal.\ndocumentation: https://runapi.ai/models.md\ncatalog: https://runapi.ai/models.md\nmetadata:\n  openclaw:\n    homepage: https://runapi.ai/models\n    primaryEnv: RUNAPI_API_KEY\n    requires:\n      bins:\n      - runapi\n    install:\n    - kind: brew\n      formula: runapi-ai/tap/runapi\n      bins:\n      - runapi\n    envVars:\n    - name: RUNAPI_API_KEY\n      required: false\n      description: Optional RunAPI API key; agents should prefer environment auth or saved shared config for headless use. Browser login can be completed with `runapi login` or the MCP `login` tool.\n---\n\n# RunAPI CLI\n\nThe `runapi` CLI is the universal execution layer for every RunAPI model that\nships a CLI service. Use it whenever an agent needs to run a one-off model task,\npass a JSON request body, wait for an async task, or script RunAPI from a\nterminal, server, or CI job.\n\n## Install\n\n| Target | Command |\n|---|---|\n| macOS / Linux (interactive) | `brew install runapi-ai/tap/runapi` |\n| Server / CI (headless) | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh` |\n| Pin a specific version | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh -s -- --version v0.1.0` |\n\nThe installer detects OS and architecture (Linux and macOS, amd64 and arm64), verifies a SHA-256 checksum from `https://runapi.ai/cli/latest.json`, and refuses to write the binary if verification fails.\n\n## Authentication\n\nCheck the current state first:\n\n```shell\nrunapi auth status\n```\n\n| Source | How |\n|---|---|\n| Environment (agent/headless default) | Read `RUNAPI_API_KEY` from the environment |\n| Saved config (agent/server/CI) | `printf '%s' \"$RUNAPI_API_KEY\" \\| runapi auth import-token --token -` (writes `~/.config/runapi/config.json` with mode 0600) |\n| Browser login (interactive fallback) | `runapi login` in a terminal, or the MCP `login` tool from an MCP host |\n\n`RUNAPI_BASE_URL` overrides the default base URL.\n\nThe RunAPI MCP Server reads the same `~/.config/runapi/config.json` as the CLI. After `runapi login` or the MCP `login` tool completes, authenticated MCP tools can use the saved credentials after the host reloads config if needed.\n\nAvoid `runapi auth import-token --token \"$KEY\"` directly — the value would be visible in `ps -ef` on shared hosts. Use stdin (`--token -`) or `RUNAPI_API_KEY` in the environment.\n\n## Discover services, commands, and fields\n\nThe CLI is JSON-first: every service exposes typed commands, and each command\ndocuments its request fields through `--help`. Always inspect before composing a\nrequest instead of guessing flags.\n\n```shell\nrunapi --help\nrunapi suno --help\nrunapi suno text-to-music --help\n```\n\n## Run a model\n\nPass the request body as JSON through `--input-file` (or `--input` for inline\nJSON, or `-` for stdin). The default flow is synchronous and polls until the\ntask completes.\n\n```shell\n# Synchronous: submit and poll until done\nrunapi suno text-to-music --input-file request.json\n\n# Asynchronous: submit and return immediately, then poll separately\nrunapi suno text-to-music --async --input-file request.json\nrunapi wait <task-id> --service suno --action text-to-music\n\n# Inspect a task without waiting\nrunapi get <task-id> --service suno --action text-to-music\n```\n\nJSON responses go to stdout; progress lines go to stderr. Pipe to `jq` for downstream parsing.\n\n## Account\n\n```shell\nrunapi account info\nrunapi account balance\n```\n\n## Live pricing\n\nPricing commands return current estimates for paid tasks. `pricing list` and\nordinary `pricing quote` calls do not require an API key. A quote with an\nAccount-owned `source_task_id` follows the normal API-key authentication rules.\n\n```shell\nrunapi pricing list --service suno\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params '{\"vocal_mode\":\"auto_lyrics\",\"prompt\":\"A chill lo-fi beat\"}'\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params-file pricing-inputs.json\n```\n\n## Local callback listeners\n\nListener access requires the credential issued by `runapi login`; an ordinary imported API key cannot list callback candidates, read a Listen Signing Secret, or open a listener. This restriction applies only to listener operations: ordinary API keys can still create and query tasks.\n\nBefore running a listener from an agent, check the saved auth and list the current member's key metadata:\n\n```shell\nrunapi auth status\nrunapi api-keys list --json\n```\n\nIf the API returns `cli_listen_required`, explain that the imported key keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override, then complete `runapi login` in their terminal (or the MCP `login` tool) and retry `runapi listen`. Do not retry with an imported API key or a management key.\n\nEach candidate contains `id`, `name`, `masked_token`, and `enabled`. Select an enabled stable `id`; names and masks are display context only, so renaming a key does not invalidate a stored selection. When more than one enabled key is available and the project does not identify one, present the candidates to the user instead of choosing one silently.\n\nSelection precedence is:\n\n1. `--callback-api-key-id <id>` for this invocation. It does not rewrite project config.\n2. `callback_api_key_id` from `.runapi.toml` at the git root, or from the current directory outside a git repository.\n3. The TTY selector. It writes the selected ID only after the server validates the listener session.\n\nNon-TTY invocations never select automatically. Without a flag or config, the `callback_api_key_required` error includes the candidate list so an agent can choose explicitly.\n\nProject config has one allowed field and is safe to commit:\n\n```toml\ncallback_api_key_id = \"token_abc123\"\n```\n\nDo not add credentials, key names, masks, signing secrets, forwarding URLs, or `base_url` to `.runapi.toml`; unknown fields are rejected.\n\nPass the selected ID explicitly from an agent. The listener receives only tasks created with that API key:\n\n```shell\nrunapi listen localhost:3000/webhooks/runapi --callback-api-key-id token_abc123\n```\n\nStartup output identifies the selected key by name, ID, and mask, prints the absolute project config path, and prints that key's stable Listen Signing Secret. To inject the secret without starting a listener, keep it out of logs and project config:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --print-secret --callback-api-key-id token_abc123)\"\n```\n\nIf the secret is exposed, rotate only the selected key's Listen Signing Secret:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --rotate-secret --callback-api-key-id token_abc123)\"\n```\n\nThis invalidates every active listener using the selected key without rotating its business API credential. Update each local verifier with the printed secret, then restart those listeners.\n\nRecovery rules:\n\n- A committed ID owned by another member is not reusable. Run `runapi api-keys list --json`, select that member's key, and pass its ID explicitly. Update the one-line project config only when the project should adopt that member-specific selection.\n- `callback_api_key_unusable` means the selected key was disabled, discarded, or lost membership. The listener exits without falling back; list keys and select another one explicitly.\n- After upgrading from the previous listener behavior, update the CLI, run `runapi login` again, restart listeners, and replace the old local webhook secret.\n\n## Temporary files\n\nModel commands accept readable local file paths in top-level media URL fields, such as `source_image_url`, `source_image_urls`, `reference_image_urls`, `first_frame_image_url`, `mask_url`, `upload_url`, or `source_audio_url`. The CLI uploads each local file before submitting the request and replaces the field value with the temporary URL. Remote `http://` and `https://` values stay unchanged.\n\nUse `runapi files create` when you need an explicit temporary URL for reuse, or when the source is Base64 encoded or already hosted at another URL.\n\n```shell\nrunapi files create ./image.png --file-name image.png\nrunapi files create --url https://cdn.runapi.ai/public/samples/mask.png --file-name image.png\nrunapi files create --base64 \"$BASE64_IMAGE\" --file-name image.png\n```\n\nThe command returns JSON with `file_name`, `url`, `size_bytes`, `mime_type`, `created_at`, and `expires_at`. The returned `url` is a one-hour temporary File Upload URL. Use it in endpoint fields that accept media URLs; check the model/action docs for the exact field name. Add `--url-only` when a script needs only the temporary URL on stdout.\n\n## Install the skill into another agent runtime\n\n```shell\nrunapi agent install-skill --target claude    # ~/.claude/skills/runapi-cli/\nrunapi agent install-skill --target codex     # ~/.codex/skills/runapi-cli/\nrunapi agent install-skill --target gemini    # ~/.gemini/skills/runapi-cli/\nrunapi agent install-skill --target openclaw  # ~/.openclaw/skills/runapi-cli/\nrunapi agent list-targets                     # JSON list with resolved paths\nrunapi agent install-skill --target-dir <path>  # custom location\n```\n\n## Troubleshooting CLI/skill drift\n\nThis skill is installed independently from the `runapi` binary and usually\ntracks the newest CLI behavior. If a command, action, flag, or input field\ndescribed here is unavailable or behaves differently, check the installed CLI\nversion and update it before changing the request:\n\n```shell\nrunapi version\nbrew upgrade runapi-ai/tap/runapi\n# or reinstall\ncurl -fsSL https://runapi.ai/cli/install.sh | sh\n```\n\nAfter updating, inspect the command help again:\n\n```shell\nrunapi --help\nrunapi <service> --help\nrunapi <service> <action> --help\n```\n\n## Safety notes for agents\n\n- Never paste API keys into example commands. Reference `RUNAPI_API_KEY` or `runapi auth import-token` instead.\n- Do not run interactive `runapi login` by default from an agent. In MCP hosts, guide the user through the `login` tool; in terminal/headless contexts, prefer `runapi auth status`, `RUNAPI_API_KEY`, and stdin token import unless the user explicitly wants browser auth.\n- Listener operations are the exception: when they return `cli_listen_required`, an imported key cannot recover. Explain that it keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override and complete browser-backed login; never store the returned credential or Listen Signing Secret in `.runapi.toml`.\n- The CLI exits non-zero on validation failures, network errors, and timeouts. Check the exit code before assuming success.\n- For long-running tasks, prefer `--async` plus a `wait` loop so the agent can release the shell promptly.\n- RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.\n\n## References\n\n- Browse every RunAPI model and its CLI service: https://runapi.ai/models.md\n\nFile v0.2.12:_meta.json\n\n{\n  \"ownerId\": \"kn70me4rk7jqjt92evshjeb5z18768g7\",\n  \"slug\": \"runapi-cli\",\n  \"version\": \"0.2.12\",\n  \"publishedAt\": 1785213921374\n}\n\nFile v0.2.12:skill-card.md\n\n## Description: <br>\nInstall and use the RunAPI CLI as the universal execution layer for running RunAPI models, checking authentication, passing JSON requests, waiting for tasks, and automating terminal workflows. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[runapi-ai](https://clawhub.ai/user/runapi-ai) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and agent operators use this skill to install, authenticate, and operate the RunAPI CLI from local machines, servers, or CI jobs for model execution, pricing, file upload, callback listener, and skill installation workflows. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Remote install scripts and CLI binaries can affect the host environment. <br>\nMitigation: Prefer the Homebrew install path when available, and review remote install scripts before using them in privileged or CI environments. <br>\nRisk: RunAPI credentials or listener secrets may persist on disk or appear in process lists when handled unsafely. <br>\nMitigation: Keep RUNAPI_API_KEY in environment-scoped secrets, import tokens through stdin when needed, avoid placing secrets in project config, and remove saved credentials when the host no longer needs them. <br>\n\n\n## Reference(s): <br>\n- [RunAPI model catalog](https://runapi.ai/models.md) <br>\n- [RunAPI models homepage](https://runapi.ai/models) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Guidance, Shell commands, Configuration] <br>\n**Output Format:** [Markdown with inline shell commands and JSON/TOML snippets] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Includes credential-handling guidance and command examples for RunAPI CLI workflows.] <br>\n\n## Skill Version(s): <br>\n0.2.12 (source: server release metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v0.2.11: 3 files, 5995 bytes\n\nFiles: skill-card.md (2726b), SKILL.md (10744b), _meta.json (130b)\n\nFile v0.2.11:SKILL.md\n\n---\nname: runapi-cli\ndescription: Install and use the RunAPI CLI as the universal execution layer for RunAPI models. Use when the user asks to run any RunAPI model from an agent, inspect auth, install RunAPI on a local machine/server/CI, pass JSON request bodies, wait for tasks, or automate RunAPI workflows from the terminal.\ndocumentation: https://runapi.ai/models.md\ncatalog: https://runapi.ai/models.md\nmetadata:\n  openclaw:\n    homepage: https://runapi.ai/models\n    primaryEnv: RUNAPI_API_KEY\n    requires:\n      bins:\n      - runapi\n    install:\n    - kind: brew\n      formula: runapi-ai/tap/runapi\n      bins:\n      - runapi\n    envVars:\n    - name: RUNAPI_API_KEY\n      required: false\n      description: Optional RunAPI API key; agents should prefer environment auth or saved shared config for headless use. Browser login can be completed with `runapi login` or the MCP `login` tool.\n---\n\n# RunAPI CLI\n\nThe `runapi` CLI is the universal execution layer for every RunAPI model that\nships a CLI service. Use it whenever an agent needs to run a one-off model task,\npass a JSON request body, wait for an async task, or script RunAPI from a\nterminal, server, or CI job.\n\n## Install\n\n| Target | Command |\n|---|---|\n| macOS / Linux (interactive) | `brew install runapi-ai/tap/runapi` |\n| Server / CI (headless) | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh` |\n| Pin a specific version | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh -s -- --version v0.1.0` |\n\nThe installer detects OS and architecture (Linux and macOS, amd64 and arm64), verifies a SHA-256 checksum from `https://runapi.ai/cli/latest.json`, and refuses to write the binary if verification fails.\n\n## Authentication\n\nCheck the current state first:\n\n```shell\nrunapi auth status\n```\n\n| Source | How |\n|---|---|\n| Environment (agent/headless default) | Read `RUNAPI_API_KEY` from the environment |\n| Saved config (agent/server/CI) | `printf '%s' \"$RUNAPI_API_KEY\" \\| runapi auth import-token --token -` (writes `~/.config/runapi/config.json` with mode 0600) |\n| Browser login (interactive fallback) | `runapi login` in a terminal, or the MCP `login` tool from an MCP host |\n\n`RUNAPI_BASE_URL` overrides the default base URL.\n\nThe RunAPI MCP Server reads the same `~/.config/runapi/config.json` as the CLI. After `runapi login` or the MCP `login` tool completes, authenticated MCP tools can use the saved credentials after the host reloads config if needed.\n\nAvoid `runapi auth import-token --token \"$KEY\"` directly — the value would be visible in `ps -ef` on shared hosts. Use stdin (`--token -`) or `RUNAPI_API_KEY` in the environment.\n\n## Discover services, commands, and fields\n\nThe CLI is JSON-first: every service exposes typed commands, and each command\ndocuments its request fields through `--help`. Always inspect before composing a\nrequest instead of guessing flags.\n\n```shell\nrunapi --help\nrunapi suno --help\nrunapi suno text-to-music --help\n```\n\n## Run a model\n\nPass the request body as JSON through `--input-file` (or `--input` for inline\nJSON, or `-` for stdin). The default flow is synchronous and polls until the\ntask completes.\n\n```shell\n# Synchronous: submit and poll until done\nrunapi suno text-to-music --input-file request.json\n\n# Asynchronous: submit and return immediately, then poll separately\nrunapi suno text-to-music --async --input-file request.json\nrunapi wait <task-id> --service suno --action text-to-music\n\n# Inspect a task without waiting\nrunapi get <task-id> --service suno --action text-to-music\n```\n\nJSON responses go to stdout; progress lines go to stderr. Pipe to `jq` for downstream parsing.\n\n## Account\n\n```shell\nrunapi account info\nrunapi account balance\n```\n\n## Local callback listeners\n\nListener access requires the credential issued by `runapi login`; an ordinary imported API key cannot list callback candidates, read a Listen Signing Secret, or open a listener. This restriction applies only to listener operations: ordinary API keys can still create and query tasks.\n\nBefore running a listener from an agent, check the saved auth and list the current member's key metadata:\n\n```shell\nrunapi auth status\nrunapi api-keys list --json\n```\n\nIf the API returns `cli_listen_required`, explain that the imported key keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override, then complete `runapi login` in their terminal (or the MCP `login` tool) and retry `runapi listen`. Do not retry with an imported API key or a management key.\n\nEach candidate contains `id`, `name`, `masked_token`, and `enabled`. Select an enabled stable `id`; names and masks are display context only, so renaming a key does not invalidate a stored selection. When more than one enabled key is available and the project does not identify one, present the candidates to the user instead of choosing one silently.\n\nSelection precedence is:\n\n1. `--callback-api-key-id <id>` for this invocation. It does not rewrite project config.\n2. `callback_api_key_id` from `.runapi.toml` at the git root, or from the current directory outside a git repository.\n3. The TTY selector. It writes the selected ID only after the server validates the listener session.\n\nNon-TTY invocations never select automatically. Without a flag or config, the `callback_api_key_required` error includes the candidate list so an agent can choose explicitly.\n\nProject config has one allowed field and is safe to commit:\n\n```toml\ncallback_api_key_id = \"token_abc123\"\n```\n\nDo not add credentials, key names, masks, signing secrets, forwarding URLs, or `base_url` to `.runapi.toml`; unknown fields are rejected.\n\nPass the selected ID explicitly from an agent. The listener receives only tasks created with that API key:\n\n```shell\nrunapi listen localhost:3000/webhooks/runapi --callback-api-key-id token_abc123\n```\n\nStartup output identifies the selected key by name, ID, and mask, prints the absolute project config path, and prints that key's stable Listen Signing Secret. To inject the secret without starting a listener, keep it out of logs and project config:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --print-secret --callback-api-key-id token_abc123)\"\n```\n\nIf the secret is exposed, rotate only the selected key's Listen Signing Secret:\n\n```shell\nRUNAPI_WEBHOOK_SECRET=\"$(runapi listen --rotate-secret --callback-api-key-id token_abc123)\"\n```\n\nThis invalidates every active listener using the selected key without rotating its business API credential. Update each local verifier with the printed secret, then restart those listeners.\n\nRecovery rules:\n\n- A committed ID owned by another member is not reusable. Run `runapi api-keys list --json`, select that member's key, and pass its ID explicitly. Update the one-line project config only when the project should adopt that member-specific selection.\n- `callback_api_key_unusable` means the selected key was disabled, discarded, or lost membership. The listener exits without falling back; list keys and select another one explicitly.\n- After upgrading from the previous listener behavior, update the CLI, run `runapi login` again, restart listeners, and replace the old local webhook secret.\n\n## Temporary files\n\nModel commands accept readable local file paths in top-level media URL fields, such as `source_image_url`, `source_image_urls`, `reference_image_urls`, `first_frame_image_url`, `mask_url`, `upload_url`, or `source_audio_url`. The CLI uploads each local file before submitting the request and replaces the field value with the temporary URL. Remote `http://` and `https://` values stay unchanged.\n\nUse `runapi files create` when you need an explicit temporary URL for reuse, or when the source is Base64 encoded or already hosted at another URL.\n\n```shell\nrunapi files create ./image.png --file-name image.png\nrunapi files create --url https://cdn.runapi.ai/public/samples/mask.png --file-name image.png\nrunapi files create --base64 \"$BASE64_IMAGE\" --file-name image.png\n```\n\nThe command returns JSON with `file_name`, `url`, `size_bytes`, `mime_type`, `created_at`, and `expires_at`. The returned `url` is a one-hour temporary File Upload URL. Use it in endpoint fields that accept media URLs; check the model/action docs for the exact field name. Add `--url-only` when a script needs only the temporary URL on stdout.\n\n## Install the skill into another agent runtime\n\n```shell\nrunapi agent install-skill --target claude    # ~/.claude/skills/runapi-cli/\nrunapi agent install-skill --target codex     # ~/.codex/skills/runapi-cli/\nrunapi agent install-skill --target gemini    # ~/.gemini/skills/runapi-cli/\nrunapi agent install-skill --target openclaw  # ~/.openclaw/skills/runapi-cli/\nrunapi agent list-targets                     # JSON list with resolved paths\nrunapi agent install-skill --target-dir <path>  # custom location\n```\n\n## Troubleshooting CLI/skill drift\n\nThis skill is installed independently from the `runapi` binary and usually\ntracks the newest CLI behavior. If a command, action, flag, or input field\ndescribed here is unavailable or behaves differently, check the installed CLI\nversion and update it before changing the request:\n\n```shell\nrunapi version\nbrew upgrade runapi-ai/tap/runapi\n# or reinstall\ncurl -fsSL https://runapi.ai/cli/install.sh | sh\n```\n\nAfter updating, inspect the command help again:\n\n```shell\nrunapi --help\nrunapi <service> --help\nrunapi <service> <action> --help\n```\n\n## Safety notes for agents\n\n- Never paste API keys into example commands. Reference `RUNAPI_API_KEY` or `runapi auth import-token` instead.\n- Do not run interactive `runapi login` by default from an agent. In MCP hosts, guide the user through the `login` tool; in terminal/headless contexts, prefer `runapi auth status`, `RUNAPI_API_KEY`, and stdin token import unless the user explicitly wants browser auth.\n- Listener operations are the exception: when they return `cli_listen_required`, an imported key cannot recover. Explain that it keeps its existing API access but cannot list or select listener keys. Ask the user to remove any `--api-key` or `RUNAPI_API_KEY` override and complete browser-backed login; never store the returned credential or Listen Signing Secret in `.runapi.toml`.\n- The CLI exits non-zero on validation failures, network errors, and timeouts. Check the exit code before assuming success.\n- For long-running tasks, prefer `--async` plus a `wait` loop so the agent can release the shell promptly.\n- RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.\n\n## References\n\n- Browse every RunAPI model and its CLI service: https://runapi.ai/models.md\n\nFile v0.2.11:_meta.json\n\n{\n  \"ownerId\": \"kn70me4rk7jqjt92evshjeb5z18768g7\",\n  \"slug\": \"runapi-cli\",\n  \"version\": \"0.2.11\",\n  \"publishedAt\": 1784535006987\n}\n\nFile v0.2.11:skill-card.md\n\n## Description: <br>\nInstall and use the RunAPI CLI as the universal execution layer for RunAPI models. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[runapi-ai](https://clawhub.ai/user/runapi-ai) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and agents use this skill to install, authenticate, inspect, and automate RunAPI CLI workflows from terminals, servers, and CI jobs. It supports running RunAPI model tasks, passing JSON requests, polling async jobs, managing local callback listeners, and handling temporary media file uploads. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill includes a remote installer script piped directly into a shell, including for server and CI use. <br>\nMitigation: Prefer the documented Homebrew formula or use a download-and-verify workf\n\nArchive v0.2.10: 3 files, 5747 bytes\n\nFiles: skill-card.md (2349b), SKILL.md (10366b), _meta.json (130b)","readmeExcerpt":"Skill: runapi-cli Owner: runapi-ai Summary: Use the RunAPI CLI for one-off artifacts and results, or RunAPI's standard x402 REST flow for wallet-funded Task calls without an API key. Use when an agent needs to discover models or prices, create a paid Task, poll its result, or run a supported CLI service. Use an SDK for app or production integration. Tags: latest:0.3.1 Version history: v0.3.1 | 2026-09-28T05:47:14.718","codeSnippets":[],"executableExamples":[{"language":"shell","snippet":"runapi auth status"},{"language":"shell","snippet":"runapi --help\nrunapi suno --help\nrunapi suno text-to-music --help"},{"language":"shell","snippet":"# Synchronous: submit and poll until done\nrunapi suno text-to-music --input-file request.json\n\n# Asynchronous: submit and return immediately, then poll separately\nrunapi suno text-to-music --async --input-file request.json\nrunapi wait <task-id> --service suno --action text-to-music\n\n# Inspect a task without waiting\nrunapi get <task-id> --service suno --action text-to-music"},{"language":"shell","snippet":"runapi account info\nrunapi account balance"},{"language":"shell","snippet":"runapi pricing list --service suno\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params '{\"vocal_mode\":\"auto_lyrics\",\"prompt\":\"A chill lo-fi beat\"}'\nrunapi pricing quote --service suno --action text_to_music --model suno-v4 \\\n  --params-file pricing-inputs.json"},{"language":"shell","snippet":"curl -fsS \"$BASE_URL/api/v1/models\""}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: runapi-cli\ndescription: Use the RunAPI CLI for one-off artifacts and results, or RunAPI's standard x402 REST flow for wallet-funded Task calls without an API key. Use when an agent needs to discover models or prices, create a paid Task, poll its result, or run a supported CLI service. Use an SDK for app or production integration.\ndocumentation: https://runapi.ai/models.md\ncatalog: https://runapi.ai/models.md\nmetadata:\n  openclaw:\n    homepage: https://runapi.ai/models\n    primaryEnv: RUNAPI_API_KEY\n    requires:\n      bins:\n      - runapi\n    install:\n    - kind: brew\n      formula: runapi-ai/tap/runapi\n      bins:\n      - runapi\n    envVars:\n    - name: RUNAPI_API_KEY\n      required: false\n      description: Optional RunAPI API key; agents should prefer environment auth or saved shared config for headless use. Browser login can be completed with `runapi login` or the MCP `login` tool.\n---\n\n# RunAPI CLI\n\nThe `runapi` CLI executes one-off artifacts or results only for services in its\ninstalled command catalog. An app, backend, worker, library, or production code\nintegration uses a RunAPI SDK instead.\n\n## Choose route\n\nUse the CLI for a one-off artifact or result. Use an SDK for an app, backend,\nworker, library, or production code. Before composing a service command,\ndiscover the installed command catalog with `runapi --help`; proceed only when\nit lists the service. An absent service routes to its SDK or public API contract,\nnot to a guessed CLI command.\n\n## Install\n\n| Target | Command |\n|---|---|\n| macOS / Linux (interactive) | `brew install runapi-ai/tap/runapi` |\n| Server / CI (headless) | `curl -fsSL https://runapi.ai/cli/install.sh \\| sh` |\n\nThe installer detects OS and architecture (Linux and macOS, amd64 and arm64), verifies a SHA-256 checksum from `https://runapi.ai/cli/latest.json`, and refuses to write the binary if verification fails.\n\n## Authentication\n\nCheck the current state first:\n\n```shell\nrunapi auth status\n```\n\n| Source | How |\n|---|---|\n| Environment (agent/headless default) | Read `RUNAPI_API_KEY` from the environment |\n| Saved config (agent/server/CI) | `printf '%s' \"$RUNAPI_API_KEY\" \\| runapi auth import-token --token -` (writes `~/.config/runapi/config.json` with mode 0600) |\n| Browser login (interactive fallback) | `runapi login` in a terminal, or the MCP `login` tool from an MCP host |\n\n`RUNAPI_BASE_URL` overrides the default base URL.\n\nThe RunAPI MCP Server reads the same `~/.config/runapi/config.json` as the CLI. After `runapi login` or the MCP `login` tool completes, authenticated MCP tools can use the saved credentials after the host reloads config if needed.\n\nAvoid `runapi auth import-token --token \"$KEY\"` directly — the value would be visible in `ps -ef` on shared hosts. Use stdin (`--token -`) or `RUNAPI_API_KEY` in the environment.\n\n## Discover services, commands, and fields\n\nThe CLI is JSON-first: every service exposes typed commands, and each command\ndocuments its request fields through `--help`. Always "},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn70me4rk7jqjt92evshjeb5z18768g7\",\n  \"slug\": \"runapi-cli\",\n  \"version\": \"0.3.1\",\n  \"publishedAt\": 1790574434718\n}"},{"path":"skill-card.md","content":"## Description:\n\nGuides agents in discovering RunAPI services and pricing, running one-off tasks with the CLI, and making wallet-funded x402 Task calls through the REST API.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[runapi-ai](https://clawhub.ai/user/runapi-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use this skill to find RunAPI models and prices, run supported one-off CLI tasks, or pay for and poll eligible REST tasks with an agent wallet.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: A remote installer may execute unreviewed code.\n\nMitigation: Prefer the package-manager install; inspect or verify the remote installer before using the curl-to-shell option.\n\nRisk: Task inputs and uploaded files are sent to RunAPI.\n\nMitigation: Use the skill only with data that may be shared with RunAPI.\n\nRisk: Wallet-funded tasks may incur charges.\n\nMitigation: Check live pricing and confirm each paid task before spending.\n\nRisk: API keys, payment signatures, and listener secrets could be exposed.\n\nMitigation: Keep secrets out of logs and project files; use environment or secure wallet authentication.\n\n## Reference(s):\n\n- [RunAPI model and CLI service documentation](https://runapi.ai/models.md)\n- [RunAPI model catalog](https://runapi.ai/models)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Shell commands, Configuration instructions]\n\n**Output Format:** [Markdown with shell commands and JSON examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [CLI responses are JSON; task results and generated file links come from RunAPI.]\n\n## Skill Version(s):\n\n0.3.1 (source: ClawHub release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Use the RunAPI CLI for one-off artifacts and results, or RunAPI's standard x402 REST flow for wallet-funded Task calls without an API key. Use when an agent needs to discover models or prices, create a paid Task, poll its result, or run a supported CLI service. Use an SDK for app or production integration. Skill: runapi-cli Owner: runapi-ai Summary: Use the RunAPI CLI for one-off artifacts and results, or RunAPI's standard x402 REST flow for wallet-funded Task calls without an API key. Use when an agent needs to discover models or prices, create a paid Task, poll its result, or run a supported CLI service. Use an SDK for app or production integration. Tags: latest:0.3.1 Version history: v0.3.1 | 2026-09-28T05:47:14.718","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1298,"uniquenessScore":46,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T04:27:27.696Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T04:27:27.696Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T06:41:57.204Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}