FrancoStino/runapi-cli

RunAPI CLI

Overview

The runapi CLI is the execution layer for RunAPI model tasks. Use it when an agent needs to generate AI images, videos, or music/audio, run a one-off model job, pass a JSON request body, wait for an async task, or script RunAPI from a terminal, server, or CI job.

Source repository: github.com/runapi-ai/cli-skill (Apache-2.0)

When to Use This Skill

• Use when the user asks to run a RunAPI model from an agent.
• Use when the user needs to inspect RunAPI CLI auth or account status.
• Use when the user wants to pass JSON request bodies to RunAPI services.
• Use when the user wants to submit async RunAPI tasks and wait for completion.
• Use when the user wants to install the RunAPI CLI on a local machine, server, or CI runner.

Install

macOS / Linux

brew install runapi-ai/tap/runapi

Server / CI

Download the installer, inspect it, then run it locally.

curl -fsSL https://runapi.ai/cli/install.sh -o runapi-install.sh
less runapi-install.sh
sh runapi-install.sh

To pin a specific version:

sh runapi-install.sh --version v0.1.0

The installer detects OS and architecture, verifies the SHA-256 checksum from https://runapi.ai/cli/latest.json, and refuses to write the binary if verification fails.

Authentication

Treat RunAPI authentication and generation as security-sensitive: commands can call remote services, consume credits, and expose account state. Review installer scripts before running them and keep API keys in environment variables or stdin, not shell history.

Check the current state first:

runapi auth status

| Source | How | |---|---| | Environment | Read RUNAPI_API_KEY from the environment | | Saved config | printf '%s' "$RUNAPI_API_KEY" \| runapi auth import-token --token - | | Browser login | runapi login only when the user explicitly wants browser auth |

RUNAPI_BASE_URL overrides the default base URL.

Avoid passing secrets directly in command arguments. Prefer RUNAPI_API_KEY or stdin token import with --token -.

Discover Services, Commands, and Fields

The CLI is JSON-first. Every service exposes typed commands, and each command documents its request fields through --help. Inspect command help before composing a request.

runapi --help
runapi suno --help
runapi suno text-to-music --help

Run a Model

Pass the request body as JSON through --input-file, --input, or stdin. The default flow is synchronous and polls until the task completes.

runapi suno text-to-music --input-file request.json

runapi suno text-to-music --async --input-file request.json
runapi wait <task-id> --service suno --action text-to-music

runapi get <task-id> --service suno --action text-to-music

JSON responses go to stdout; progress lines go to stderr. Pipe to jq for downstream parsing.

Account

runapi account info
runapi account balance

Install the Skill Into Another Agent Runtime

runapi agent install-skill --target claude
runapi agent install-skill --target codex
runapi agent install-skill --target gemini
runapi agent install-skill --target openclaw
runapi agent list-targets
runapi agent install-skill --target-dir <path>

Limitations

• RunAPI model calls require a valid RunAPI account or API key.
• Some model tasks are long-running and should use --async plus runapi wait.
• Browser login is interactive and should not be the default path for agents.
• This skill does not replace model-specific parameter validation; inspect command help before building request JSON.

Security & Safety Notes

• Never paste API keys into example commands or PR text.
• Prefer RUNAPI_API_KEY or stdin token import instead of command-line secrets.
• Do not run interactive runapi login by default from an agent.
• Check the CLI exit code before assuming a task succeeded.

References

• RunAPI CLI skill: https://github.com/runapi-ai/cli-skill
• RunAPI CLI repository: https://github.com/runapi-ai/cli
• RunAPI model catalog: https://runapi.ai/models.md