1
Check your environment and run the CLI
Node.js 20 or newer is required. If node --version prints v20 or higher, run the CLI directly through npx without a global install.
node --version
npx -y @poyoapi/cli helpPoYo CLInpm package available
Every PoYo model — from your terminal, scripts, and agents.
Browse input schemas and public prices for models currently available in the live PoYo Catalog without an API Key. Add a Key only when you execute a model. If a job takes longer than the CLI waits, continue checking it with the same task_id.
$npx -y @poyoapi/cli helpThree steps from discovery to result
No global install required. Check Node.js, inspect the model, authenticate, and complete your first run.
2
Find and inspect a model
This example finds the currently available gpt-image-2 model, then reads its live input Schema and public price. Neither command requires an API Key.
npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1
npx -y @poyoapi/cli describe gpt-image-23
Sign in, verify, and execute
Create an API Key, then complete the three commands below in order. Check the price with describe before the paid run; failed generations do not consume credits.
Create API Key1. Save your API Key
Expected: the CLI asks for the Key without echoing it, then reports keyring or config as the save location. If the system credential store is unavailable, it falls back to your PoYo config file.
npx -y @poyoapi/cli auth login2. Verify the account and balance
Expected: account details and the available balance. A 401 means the Key is missing or invalid.
npx -y @poyoapi/cli account3. Confirm the price and run
This is a paid request. A successful JSON result includes the task_id, final status, and output files.
npx -y @poyoapi/cli run gpt-image-2 --prompt "cinematic product photo" --format jsonBuilt for real multimodal workflows
The live Catalog tells the CLI which models exist, which inputs they accept, how long jobs are tracked, and which output format scripts receive.
Search before you execute
models lists the public catalog. describe returns the exact Schema, supported protocols, execution mode, callback support, and billing metadata for one model.
These two commands do not require an API Key.
Schema becomes command flags
The CLI reads each model's live Schema and exposes its fields as model-specific command-line options.
Unknown model flags fail locally. Required-field and complete JSON Schema validation still happen on the API.
Submit once, continue by task_id
submit returns a task_id immediately. task get reads the current state, while task wait keeps polling until completion or timeout.
Prefer submit for video, audio, 3D, and other long-running jobs.
Structured output for scripts and CI
Choose table output for people; use JSON, JSONL, or CSV for scripts and CI. Non-streaming commands can also write results to a file.
Use --output FILE with non-streaming commands. Streaming text and JSONL stay on stdout.
What a real PoYo session looks like
Browse the public catalog, inspect one model's current inputs and price, then request structured output for your scripts.
~/projects/poyo-demo
# 1. Find and inspect a model
$ npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1
# 2. Inspect the live Schema
$ npx -y @poyoapi/cli describe gpt-image-2
prompt string required
size string default: "1:1"
output_format string enum: jpeg | png
# 3. Sign in, verify, and execute
$ npx -y @poyoapi/cli run gpt-image-2 --prompt "cinematic product photo" --size 4:3 --output-format png --format json
{
"task_id": "task_7f31b2",
"status": "succeeded",
"files": ["https://storage.poyo.ai/.../image.png"]
}Task lifecycle
Long jobs don't have to start over
Submit video, audio, 3D, and other long-running work once. Keep the task_id and continue waiting from another terminal or CI step.
A CLI timeout does not cancel the backend job. Continue with the same task_id instead of submitting the same work again.
Use submit when the terminal should not wait
$ npx -y @poyoapi/cli submit gpt-image-2 --prompt "cinematic product photo" --format jsontask_id task_7f31b2
$ npx -y @poyoapi/cli task wait TASK_ID --timeout 300 --format jsonstatus succeeded
Use run when 90 seconds is enough
run checks the task every two seconds and waits up to 90 seconds by default. You can set a different timeout.
Use submit when the terminal should not wait
Copy the task_id returned by submit and replace TASK_ID in the wait command. You can continue from another terminal or CI step.
Use the right interface for the caller
Use CLI for people and shell scripts, MCP for Agent tool calls, REST inside applications, and Skill to give an Agent reusable PoYo steps and safety rules.
PoYo CLI
Developers, terminals, and CI
A person or shell script needs to discover models, run them, resume tasks, and act on process exit codes.
Install CLIMCP
AI agents and coding clients
An Agent should discover schemas, prices, and execution tools through one connection.
View MCPREST API
Applications and services
Your application needs direct HTTP control over requests, streaming, retries, and callbacks.
Open docsPoYo Skill
Repeatable Agent workflows
An Agent needs reusable operating steps and safety rules alongside CLI, MCP, or REST access.
View SkillPoYo CLI FAQ
Still unsure about a command? Contact PoYo support→
PoYo CLI is a command-line client for discovering and calling PoYo chat, image, video, audio, and 3D models. It reads current model definitions from the public Capability Catalog, turns Schema fields into command options, and uses the same PoYo API endpoints for execution and task status.
models and describe read the public Capability Catalog without credentials. Chat, generation, task, account, and paid execution commands require an API Key.
run waits for 90 seconds by default. A timeout stops local polling but does not cancel the backend task. Continue with npx -y @poyoapi/cli task wait TASK_ID.
Store the Key in your CI secret manager and expose it as POYO_API_KEY. Pin @poyoapi/cli@VERSION for reproducible runs, request --format json, and treat any non-zero exit as failure. Never place credentials in command history or repository files.
No. The CLI calls the same endpoints. describe shows the selected model's public price and account shows your current balance. run and submit are paid; credits are deducted only when a generation succeeds. A 401 means the Key is missing or invalid, while 402 means the account has insufficient credits.
It runs a stdio bridge that forwards JSON-RPC messages to https://api.poyo.ai/mcp. Model execution remains on PoYo's remote service.
Open source. Ready from any terminal.
The MIT-licensed CLI is published on npm and developed on GitHub. Browse the public Catalog first, then create an API Key when you are ready to run a model.