CLI

Commands

Every riffads command, its flags, output and exit codes.

Read as Markdown

Install 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

CommandWhat it doesKey needsNew in
login, logout, whoamiSave, delete or check the key
creditsBalance, and the most one job may cost
capabilitiesWhat you can generate
presetsAd formats and their templates0.2.0
actors, voicesActor (act_) and voice (voc_) ids
estimatePrice a job. Free
generateSpends credits. Run a job, wait, save the filesGenerate
analyzeSpends credits. Break an ad down into JSONGenerate0.2.0
statusRead one generation (gen_)
batchRead every take of one --variants submit (bg_)
listPast generations, newest first0.2.0
downloadSave a generation's files, or one library fileasset ids: 0.2.0
uploadUpload or import a file, print its ast_ idGenerate--url, --filename: 0.2.0
searchFind files in the library0.2.0
workflowsTemplates, runs (spends credits), run historyWorkflows (invoke)runs: 0.2.0
webhooksList, create or delete webhook endpointsGenerate (create, delete)0.2.0
  • A blank "Key needs" means any key works. logout needs no key.
  • Aliases: ls is capabilities, balance is credits, get is status. ls is not list.
  • --version, -v and version print the version.
  • The MCP tool and REST route for each job: Same job, every surface.

Global options

They work before or after the command.

FlagWhat it does
--jsonFull API response as JSON on stdout
--quiet, -qHide 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, -hHelp for the command
  • Write --json and --quiet bare: --json=true does not switch the output.
  • An unknown option exits 2 and suggests the closest flag.

Account

Terminal
riffads login
riffads whoami
riffads credits --json | jq .most_one_generation_may_cost
  • login exits 0 when saved, 2 with no key, 3 when the key is refused. logout makes no network call and exits 0.
  • credits (alias balance) prints two lines: available (the balance) and per job (the most one job may cost right now).
  • per job already 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

Terminal
riffads capabilities
riffads capabilities show kling_3_pro --example > clip.json
  • capabilities prints 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. --schema or --example prints only that JSON.
  • show is required: riffads capabilities <capability-id> without it exits 2.

What each field means: Read one schema.

presets

Terminal
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, passing template_id with --set-string so 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

Terminal
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 for voices only.
  • actors --json adds default_voice_id, default_voice_name and is_platform.

Generate

Passing a config

Used by estimate and generate.

FlagWhat it does
--config '{"prompt": "..."}'Inline JSON, for one or two fields
--config @clip.jsonA 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.
  • --set applies after --config, so a saved config plus one changed field works.
  • Dotted paths nest: --set a.b=1 sets b to 1 inside the object a.

clip.json, used in the examples below:

clip.json
{
  "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

Terminal
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-credits to send.
  • --json adds is_ceiling, max_credits_needed, summary, and sometimes note.
  • For generate --variants N, estimate with --set count=N.

Why you send max_credits_needed: Price first.

generate

Terminal
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
FlagDefaultWhat it does
--capability <id>, -crequiredCapability to run
--config, --set, --set-string{}The config
--max-credits <n>, -mrequiredMost the job may cost, all takes counted: the estimate's max_credits_needed
--variants <n>1Takes 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-waitoffPrint the ids and exit 0
--timeout <seconds>1800Stop waiting after this
--output <dir>, -oSave the files here
  • stdout: the ids, then with -o one 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-credits exits 2. The bare price is refused with max_credits_exceeded, exit 4.
  • A wait that hits --timeout exits 5 and cancels nothing. A file already in the -o folder exits 2.
  • A video model with --variants fans out, and generate follows 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.

Terminal
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 ./out

analyze

Runs Analyze Media on one video (up to 3 minutes) or one image. It spends credits.

Terminal
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).
  • -m is required, and checked before any upload. --focus <text> becomes config.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

Terminal
riffads status <generation-id> [--wait] [--timeout <seconds>]
  • Alias get. --wait (-w) blocks until the job ends (--timeout default 1800).
  • stdout: queued, rendering, post_processing, completed or failed (a canceled job reads failed).
  • A job still running exits 0, or 5 when --wait hits the timeout. Only a finished job exits 6 or 7.
  • stderr: a plain summary, like Making your video. or Your video is ready. Charged 100 credits., then each file's link.
  • Under --json: generation.summary, text answers in generation.output_text, and outputs[].url and outputs[].asset_id once the charge is final.

batch

Terminal
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

Terminal
riffads list --since 2026-09-01T00:00:00Z --all --json | jq -r '.generations[].generation_id'
FlagWhat it does
--status <status>queued, rendering, post_processing, completed or failed
--capability <id>, -cOnly 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 yet until the charge is final. Never read it as 0.
  • Send --cursor back with the same filters. Workflow steps list with source workflow.

download

Terminal
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>.part first, so a rerun resumes, however late it comes.
  • An existing file without --force exits 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

Terminal
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). .m4a and .aac are 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 is usable, 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.

Terminal
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 --limit while more exist, so use --all.

Workflows

Terminal
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,queued

The example runs the Creator to camera template. riffads workflows templates prints every template's key and inputs.

FlagWhat it does
--template <key>invoke a template, not a saved workflow
--max-credits <n>, -mRequired to invoke. Most the whole run may cost, every step counted
--input <node.field=value>, -iOne input on one node. Repeatable
--wait, -wFollow 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.
  • invoke takes a workflow id or --template, not both, and prints the run id (wfr_). --input splits on the first = and the last . before it.
  • There is no run estimate. A -m too low exits 4 before anything starts and names the number it needs (limit.required_credits).
  • invoke prints a plain sentence on stderr, like Started. It takes a few minutes and costs up to 900 credits.
  • run prints the status on stdout. stderr shows one line per step with its files, then a plain summary and run total.
  • A run has one money number, its total. It reads not final yet until the run ends. A run still going exits 5, even without --wait.
  • runs lists 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 a runs row.

Templates, inputs and run pricing: Run a workflow.

Webhooks

Terminal
riffads webhooks
riffads webhooks create --url https://example.com/hooks/riffads \
  -e generation.completed,generation.failed > signing-secret.txt
riffads webhooks delete <webhook-id>
  • create needs --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.
  • create prints the signing secret (whsec_...) on stdout once (secret under --json). If you lose it, delete the endpoint and create a new one.
  • list (the default) prints one line per endpoint (wh_ id). delete prints the deleted id.
  • A missing --url or --event, or an unknown subcommand, exits 2.

Payloads and signature checks: Webhooks.

Output

  • stdout is data: ids, file paths, status words, list rows, the analyze breakdown, the webhook secret, --json bodies.
  • stderr is for people: spinner, the server's plain summary with the cost, each file's link, hints, warnings, errors.
  • A failure under --json prints the error on stdout, in the same envelope the API sends. A missing --max-credits:
stdout
{
  "error": {
    "ok": false,
    "code": "invalid_config",
    "message": "--max-credits is required, for example --max-credits 400.",
    "retryable": false,
    "credits_charged": 0
  }
}
CommandRead in --json
generate --no-waitgeneration_ids, batch_group_id, summary
generate, status, analyzegeneration.summary, generation.outputs, generation.output_text, generation.result, generation.credits_charged
generate --variants on a video model, batchgenerations, summary, credits_charged
estimatecredits, max_credits_needed, summary
creditscredits_available, most_one_generation_may_cost
list, search, workflows runsgenerations, assets or runs, and next_cursor
  • generate --json prints the id lines before the JSON, so it does not pipe into jq. Take the id with --no-wait (no --json), then read status <id> --wait --json.
  • credits_charged is null until the charge is final. Never read null as 0.
  • 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 null until 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

ExitMeaningError codes and cases
0Worked. Also a job still running on status or --no-wait
1Something broke. Tell a humaninternal_error
2Change the requestinvalid_config, capability_unavailable, not_found, moderation_blocked, request_blocked, a bad flag, an unusable file, a file already on disk
3Fix the key, scope, plan or workspacenot_authorized, no_workspace, workspace_unavailable, required_plan, insufficient_scope
4Not enough credits, or a spend limitinsufficient_credits, max_credits_exceeded, spend_limit_exceeded, not_priced, quota_exceeded
5Safe to send again, or still runninginput_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
6The job or run failed, nothing charged
7Only part arrived, or it failed after a charge
130Ctrl+C. The job keeps running
  • A refused submit never exits 6 or 7: those are job outcomes.
  • internal_error is retryable: true on 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_seconds or 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

ci-generate.sh
#!/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 the case runs.
  • Take MAX from the estimate on every run. Never hardcode it.

On this page