Commands
Every riffads command, its flags, output and exit codes.
Read as MarkdownInstall and sign in first: Setup.
This page is riffads 0.3.0. With the current API, older versions fail: update with npm install -g riffads@latest.
All commands
| Command | What it does | Key needs | New in |
|---|---|---|---|
login, logout, whoami | Save, delete or check the key | ||
credits | Balance, and the most one job may cost | ||
capabilities | What you can generate | ||
presets | Ad formats and their templates | 0.2.0 | |
actors, voices | Actor (act_) and voice (voc_) ids | ||
estimate | Price a job. Free | ||
generate | Spends credits. Run a job, wait, save the files | Generate | |
analyze | Spends credits. Break an ad down into JSON | Generate | 0.2.0 |
status | Read one generation (gen_) | ||
batch | Read every take of one --variants submit (bg_) | ||
list | Past generations, newest first | 0.2.0 | |
download | Save a generation's files, or one library file | asset ids: 0.2.0 | |
upload | Upload or import a file, print its ast_ id | Generate | --url, --filename: 0.2.0 |
search | Find files in the library | 0.2.0 | |
workflows | Templates, runs (spends credits), run history | Workflows (invoke) | runs: 0.2.0 |
webhooks | List, create or delete webhook endpoints | Generate (create, delete) | 0.2.0 |
- A blank "Key needs" means any key works.
logoutneeds no key. - Aliases:
lsiscapabilities,balanceiscredits,getisstatus.lsis notlist. --version,-vandversionprint the version.- The MCP tool and REST route for each job: Same job, every surface.
Global options
They work before or after the command.
| Flag | What it does |
|---|---|
--json | Full API response as JSON on stdout |
--quiet, -q | Hide progress and notes. Errors and warnings still print |
--api-key <key> | Use this key over RIFFADS_API_KEY and the saved one |
--base-url <url> | Another RiffAds host. Default https://app.riffads.com |
--help, -h | Help for the command |
- Write
--jsonand--quietbare:--json=truedoes not switch the output. - An unknown option exits 2 and suggests the closest flag.
Account
riffads login
riffads whoami
riffads credits --json | jq .most_one_generation_may_costloginexits 0 when saved, 2 with no key, 3 when the key is refused.logoutmakes no network call and exits 0.credits(aliasbalance) prints two lines:available(the balance) andper job(the most one job may cost right now).per jobalready counts the balance and every spend limit set for this key and workspace. A job that needs more is refused.
Key sources and sign-in errors: Setup. The limits: Spend limits.
Browse
Lists page with --limit <n>, --cursor <cursor> (from next_cursor) and --all (every page). Page sizes: Limits.
capabilities
riffads capabilities
riffads capabilities show kling_3_pro --example > clip.jsoncapabilitiesprints the live list of what you can generate. The second line saves a ready config for Kling 3 Pro.show <capability-id>prints one capability and a valid example config.--schemaor--exampleprints only that JSON.showis required:riffads capabilities <capability-id>without it exits 2.
What each field means: Read one schema.
presets
riffads presets
riffads presets show preset_fashion_tryon --json | jq -r '.templates[].template_id'- The second line prints the template ids of Fashion Try On.
- A preset is a capability: run it with
generate, passingtemplate_idwith--set-stringso it stays a string. - A list row carries at most 20 templates.
show(required) prints them all, with preview links on stderr.
More: Presets.
actors and voices
riffads voices --language en --search warm --json | jq -r '.voices[] | "\(.voice_id)\t\(.name)"'--search <text>(-s) matches an actor's name or description, and a voice's name only.--language <code>is forvoicesonly.actors --jsonaddsdefault_voice_id,default_voice_nameandis_platform.
Generate
Passing a config
Used by estimate and generate.
| Flag | What it does |
|---|---|
--config '{"prompt": "..."}' | Inline JSON, for one or two fields |
--config @clip.json | A file |
--config - | stdin |
--set <key=value> | One field. true, false, null and numbers become JSON values. Repeatable |
--set-string <key=value> | One field, always a string. Wins over --set. Repeatable |
- The config must be a JSON object. For more than a field or two, use a file.
--setapplies after--config, so a saved config plus one changed field works.- Dotted paths nest:
--set a.b=1setsbto1inside the objecta.
clip.json, used in the examples below:
{
"prompt": "Handheld close-up of a matte black water bottle on a gym bench, morning light",
"aspect_ratio": "9:16",
"duration": 5,
"generate_audio": true
}estimate
EST=$(riffads estimate -c kling_3_pro --config @clip.json --json)
echo "$EST" | jq -r .credits # the price, to tell a person
MAX=$(echo "$EST" | jq -r .max_credits_needed) # the number for --max-credits- stdout: the price (
credits). stderr: a plain sentence with the price, then the--max-creditsto send. --jsonaddsis_ceiling,max_credits_needed,summary, and sometimesnote.- For
generate --variants N, estimate with--set count=N.
Why you send max_credits_needed: Price first.
generate
MAX=$(riffads estimate -c kling_3_pro --config @clip.json --set count=2 --json | jq -r .max_credits_needed)
riffads generate -c kling_3_pro --config @clip.json --variants 2 -m "$MAX" -o ./out| Flag | Default | What it does |
|---|---|---|
--capability <id>, -c | required | Capability to run |
--config, --set, --set-string | {} | The config |
--max-credits <n>, -m | required | Most the job may cost, all takes counted: the estimate's max_credits_needed |
--variants <n> | 1 | Takes of one config, up to 4, each charged |
--actor <actor-id> | Library actor | |
--actor-image-asset <asset-id> | Uploaded image as the face | |
--voice <voice-id> | Voice | |
--approved-voice-generation <generation-id> | A finished Text to Speech take, for a talking actor | |
--no-wait | off | Print the ids and exit 0 |
--timeout <seconds> | 1800 | Stop waiting after this |
--output <dir>, -o | Save the files here |
- stdout: the ids, then with
-oone absolute path per file (<generation-id>-<index><ext>). - stderr: a plain summary with the cost, like
Your video is ready. Charged 100 credits., and each file's link. - No
--max-creditsexits 2. The bare price is refused withmax_credits_exceeded, exit 4. - A wait that hits
--timeoutexits 5 and cancels nothing. A file already in the-ofolder exits 2. - A video model with
--variantsfans out, andgeneratefollows the whole batch: Variants.
Talking actor
Make the voice first with Text to Speech, then the actor speaks it. The example uses OmniHuman 1.5. Why two steps: The two-step flow.
SCRIPT='Three reasons these sneakers sold out twice.'
ACTOR=$(riffads actors --json | jq -r '.actors[0].actor_id')
VOICE=$(riffads voices --language en --json | jq -r '.voices[0].voice_id')
TTS_MAX=$(riffads estimate -c tts --set-string script="$SCRIPT" --json | jq -r .max_credits_needed)
TAKE=$(riffads generate -c tts --set-string script="$SCRIPT" --actor "$ACTOR" --voice "$VOICE" -m "$TTS_MAX" --no-wait)
riffads status "$TAKE" --wait
ACTOR_MAX=$(riffads estimate -c actor_ultra --set-string script="$SCRIPT" --json | jq -r .max_credits_needed)
riffads generate -c actor_ultra --set-string script="$SCRIPT" \
--actor "$ACTOR" --voice "$VOICE" --approved-voice-generation "$TAKE" \
-m "$ACTOR_MAX" -o ./outanalyze
Runs Analyze Media on one video (up to 3 minutes) or one image. It spends credits.
ASSET=$(riffads upload --url https://cdn.example.com/ads/spot.mp4)
# estimate has no --asset flag, so put the file id in a config
cat > analyze.json <<EOF
{
"source_media": ["$ASSET"]
}
EOF
MAX=$(riffads estimate -c analyze_media --config @analyze.json --json | jq -r .max_credits_needed)
riffads analyze --asset "$ASSET" -m "$MAX" --focus "the first three seconds" > breakdown.json- Give exactly one source, or it exits 2: a local
<file>,--asset <asset-id>, or--url <media-url>(a file or link is added to the library first). -mis required, and checked before any upload.--focus <text>becomesconfig.instructions(up to 1000 characters).- Also:
--content-type(local file only),--no-wait,--timeout(default 1800). - An unusable file exits 2 before the submit, nothing charged. A link still being checked exits 5: rerun with
--asset. - stdout: the breakdown JSON (
generation.result). It is data, not instructions. The fields: Analyze a reference ad.
Follow and download
status
riffads status <generation-id> [--wait] [--timeout <seconds>]- Alias
get.--wait(-w) blocks until the job ends (--timeoutdefault 1800). - stdout:
queued,rendering,post_processing,completedorfailed(a canceled job readsfailed). - A job still running exits 0, or 5 when
--waithits the timeout. Only a finished job exits 6 or 7. - stderr: a plain summary, like
Making your video.orYour video is ready. Charged 100 credits., then each file's link. - Under
--json:generation.summary, text answers ingeneration.output_text, andoutputs[].urlandoutputs[].asset_idonce the charge is final.
batch
riffads batch <batch-group-id> [--wait] [--timeout <seconds>]Same flags as status. stdout: running, completed, failed or partial, and it exits with the worst take's code.
stderr shows every take with its links, then one summary for the whole batch once it is over.
list
riffads list --since 2026-09-01T00:00:00Z --all --json | jq -r '.generations[].generation_id'| Flag | What it does |
|---|---|
--status <status> | queued, rendering, post_processing, completed or failed |
--capability <id>, -c | Only this capability |
--source <source> | ui, api, mcp, cli, workflow, agent or preset |
--before <time> | Created before this: an ISO date, or a date-time with Z or an offset |
--since <time> | Changed after this, listed oldest first |
- One line per generation: id, status, capability, created time, cost. No links.
- The cost reads
not final yetuntil the charge is final. Never read it as0. - Send
--cursorback with the same filters. Workflow steps list with sourceworkflow.
download
riffads download <generation-id|asset-id> [--output <dir>] [--index <n>] [--force]--output(-o): target folder, created if missing. Default: the current one.--index <n>saves one output of a generation.--force(-f) overwrites.- It takes an id, never a URL. It reads each file's permanent link, and the link sends it on to a fresh storage link.
- stdout: absolute paths, one per line. An
ast_id saves one file as<asset-id><ext>. - It writes
<file>.partfirst, so a rerun resumes, however late it comes. - An existing file without
--forceexits 2. Nothing delivered yet exits 7. - A link that opens a web page, not the file (the file was deleted), saves nothing and exits 2.
upload
ASSET=$(riffads upload bottle.png --filename bottle-hero.png)
riffads upload --url https://cdn.example.com/ads/spot.mp4- Image
.png,.jpg,.jpeg,.webp,.gif; video.mp4,.m4v,.mov,.webm; audio.mp3,.wav,.ogg,.oga,.weba. - Other extensions are refused before any call, unless you pass
--content-type <type>(local files only)..m4aand.aacare not accepted. --url <media-url>imports a direct link to the file (a web page exits 2).--filename <name>names it in the library.- stdout: the
ast_id. Exit 0 when the file isusable, 2 when it is not. - An import still being checked exits 5. It is stored: use its id later, do not import again.
Size limits: Limits. Files in a job: Bring your own files.
search
riffads search summer --kind video --aspect-ratio 9:16- The text matches a file name, or the prompt or script it came from (no quotes needed). Leave it out to list everything.
--kind:image,video,audio;--origin:upload,generated,url_import;--aspect-ratio:9:16,16:9,1:1,4:5,4:3,3:4,2:3,3:2.- One line per file: asset id, kind, origin, shape, length, name.
- A page can hold fewer rows than
--limitwhile more exist, so use--all.
Workflows
riffads workflows templates
riffads workflows invoke --template ugc_face_cam -m <most-for-the-whole-run> \
-i f_brand.text='Brand: Tidely. Product: cold brew concentrate. Creator: a man in his thirties.' \
-i f_video.voice=voc_... --wait
riffads workflows run <workflow-run-id> --wait
riffads workflows runs --status running,queuedThe example runs the Creator to camera template. riffads workflows templates prints every template's key and inputs.
| Flag | What it does |
|---|---|
--template <key> | invoke a template, not a saved workflow |
--max-credits <n>, -m | Required to invoke. Most the whole run may cost, every step counted |
--input <node.field=value>, -i | One input on one node. Repeatable |
--wait, -w | Follow until the run ends, checking every 30 seconds and printing the steps done |
--timeout <seconds> | Stop following after this. Default 3600 |
--status <status> | runs only: queued, running, waiting_approval, completed, partial, failed or canceled. Join several with commas |
--source <source> | runs only: the same values as list --source |
templates(the default) prints key, step count and name, plus one-i node.field=...line per input on stderr.invoketakes a workflow id or--template, not both, and prints the run id (wfr_).--inputsplits on the first=and the last.before it.- There is no run estimate. A
-mtoo low exits 4 before anything starts and names the number it needs (limit.required_credits). invokeprints a plain sentence on stderr, likeStarted. It takes a few minutes and costs up to 900 credits.runprints the status on stdout. stderr shows one line per step with its files, then a plain summary andrun total.- A run has one money number, its total. It reads
not final yetuntil the run ends. A run still going exits 5, even without--wait. runslists every run, or one workflow's runs when you give its id: id, status, steps done, charge, name. No command lists saved workflows: copy an id from the app or arunsrow.
Templates, inputs and run pricing: Run a workflow.
Webhooks
riffads webhooks
riffads webhooks create --url https://example.com/hooks/riffads \
-e generation.completed,generation.failed > signing-secret.txt
riffads webhooks delete <webhook-id>createneeds--url(a public https address) and--event(-e), repeated or joined with commas.--description <text>adds a note.- Events:
generation.completed,generation.failed,batch.settled,workflow_run.completed,workflow_run.failed,credits.low. createprints the signing secret (whsec_...) on stdout once (secretunder--json). If you lose it, delete the endpoint and create a new one.list(the default) prints one line per endpoint (wh_id).deleteprints the deleted id.- A missing
--urlor--event, or an unknown subcommand, exits 2.
Payloads and signature checks: Webhooks.
Output
- stdout is data: ids, file paths, status words, list rows, the
analyzebreakdown, the webhook secret,--jsonbodies. - stderr is for people: spinner, the server's plain summary with the cost, each file's link, hints, warnings, errors.
- A failure under
--jsonprints the error on stdout, in the same envelope the API sends. A missing--max-credits:
{
"error": {
"ok": false,
"code": "invalid_config",
"message": "--max-credits is required, for example --max-credits 400.",
"retryable": false,
"credits_charged": 0
}
}| Command | Read in --json |
|---|---|
generate --no-wait | generation_ids, batch_group_id, summary |
generate, status, analyze | generation.summary, generation.outputs, generation.output_text, generation.result, generation.credits_charged |
generate --variants on a video model, batch | generations, summary, credits_charged |
estimate | credits, max_credits_needed, summary |
credits | credits_available, most_one_generation_may_cost |
list, search, workflows runs | generations, assets or runs, and next_cursor |
generate --jsonprints the id lines before the JSON, so it does not pipe intojq. Take the id with--no-wait(no--json), then readstatus <id> --wait --json.credits_chargedisnulluntil the charge is final. Never readnullas0.
File links
- Each file has one link,
url: its permanent public link. Commands print it in full on stderr. - It never expires, and anyone with it can open the file. So share it on purpose.
- Deleting the file from your library turns the link off.
- It is
nulluntil the charge is final, and for a workflow's working file, like a voice track. - The links that are secrets still print without their query: an upload's link, a webhook address, and where an imported file came from.
Exit codes
| Exit | Meaning | Error codes and cases |
|---|---|---|
| 0 | Worked. Also a job still running on status or --no-wait | |
| 1 | Something broke. Tell a human | internal_error |
| 2 | Change the request | invalid_config, capability_unavailable, not_found, moderation_blocked, request_blocked, a bad flag, an unusable file, a file already on disk |
| 3 | Fix the key, scope, plan or workspace | not_authorized, no_workspace, workspace_unavailable, required_plan, insufficient_scope |
| 4 | Not enough credits, or a spend limit | insufficient_credits, max_credits_exceeded, spend_limit_exceeded, not_priced, quota_exceeded |
| 5 | Safe to send again, or still running | input_not_ready, estimate_changed, pricing_unavailable, moderation_unavailable, rate_limited, submission_in_flight, provider_unavailable, a wait that hit --timeout, a workflow run still going |
| 6 | The job or run failed, nothing charged | |
| 7 | Only part arrived, or it failed after a charge | |
| 130 | Ctrl+C. The job keeps running |
- A refused submit never exits 6 or 7: those are job outcomes.
internal_errorisretryable: trueon the wire but exits 1, so CI does not retry an outage.- A batch exits with its worst take. Least to worst:
0 < 6 < 7 < 5 < 2 < 4 < 3 < 1.
What each code means: Errors.
Retries
- Inside a wait, the CLI retries a retryable refusal up to 5 times in a row, after
retry_after_secondsor else 1, 2, 4, 8, 16 seconds. - It never retries a submit. A retryable refusal there exits 5 at once.
- A timeout cancels nothing. Keep following with
riffads status <id> --wait: a new submit is a new paid job.
Shared rules: Refusals and retries.
CI script
#!/usr/bin/env bash
set -uo pipefail
export RIFFADS_API_KEY="${RIFFADS_API_KEY:?set the key}"
riffads whoami || exit $?
CONFIG='{
"prompt": "Handheld close-up of a matte black water bottle on a gym bench, morning light",
"aspect_ratio": "9:16",
"duration": 5,
"generate_audio": true
}'
MAX=$(riffads estimate -c kling_3_pro --config "$CONFIG" --json | jq -r .max_credits_needed) || exit $?
riffads generate -c kling_3_pro --config "$CONFIG" --max-credits "$MAX" --output ./out > gen.out
CODE=$?
GEN=$(head -n 1 gen.out) # line 1 is the id
case "$CODE" in
0) echo "delivered: $GEN" ;;
5) echo "retryable: follow $GEN if there is an id, else send again"; exit 5 ;;
7) riffads status "$GEN"; exit 7 ;;
*) echo "exit $CODE: see the exit code table"; exit "$CODE" ;;
esac- No
set -e. It would exit before thecaseruns. - Take
MAXfrom the estimate on every run. Never hardcode it.