CLI

Setup

Install the riffads CLI, sign in, and make your first video.

Read as Markdown

Install riffads, give it an API key, and make one video from your terminal.

You need

  • Node 20.10.0 or newer, and jq for the examples.
  • An API key (sk_live_...) with Generate ticked, plus Workflows for workflow runs.
  • A server, a build box or your own machine. Never a browser: the key is a secret.

Owners and admins create keys on the API keys page:

Install

Terminal
npm install -g riffads

# or run it without installing
npx riffads@latest --version

The package on npm:

Use riffads 0.3.0 or newer

The API now answers every job in one plain shape. Versions before 0.3.0 read fields it no longer returns, and fail. Update with npm install -g riffads@latest.

Check yours with riffads --version.

Sign in

Terminal
riffads login

login checks the key, then saves it. A refused key exits 3 and saves nothing.

login looks for the key in this order. The first match wins:

OrderSourceNotes
1--api-key <key>Lands in shell history. Avoid it
2RIFFADS_API_KEYThe environment variable
3stdin, when pipedpass show riffads/ci | riffads login
4Hidden promptTerminal only, so CI never hangs
  • Every other command reads --api-key, then RIFFADS_API_KEY, then the saved key. An empty value counts as not set.
  • The key is saved in ~/.riffads/config.json with mode 0600.

Check it

Terminal
riffads whoami
stdout
host    https://app.riffads.com (from default)
key     ****a91f (from file)
credits 4,200 credits

Does it say (from env) and show the wrong workspace? Unset RIFFADS_API_KEY: it beats the saved key.

First video

Kling 3 Pro makes a video from one prompt. Save the config as clip.json:

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
}

Price it, then run it with the number the estimate gives you:

Terminal
# free: the estimate gives the number to send
MAX=$(riffads estimate -c kling_3_pro --config @clip.json --json | jq -r .max_credits_needed)

riffads generate -c kling_3_pro --config @clip.json --max-credits "$MAX" --output ./out
  • generate waits, then saves <generation-id>-0.mp4 in ./out. stdout prints the id, then the path.
  • stderr prints a plain summary, like Your video is ready. Charged 100 credits., and the file's link.
  • The link is permanent and public: it never expires, and anyone with it can open the file. Share it on purpose.
  • Ctrl+C stops the wait, not the job, and exits 130. Save the file again later with riffads download <generation-id> -o ./out.
  • Want a different model? riffads capabilities lists every one you can run.

Why --max-credits takes the estimate's max_credits_needed, not the bare price: Price first.

Environment variables

VariableEffectDefault
RIFFADS_API_KEYThe key. Beats the saved onenone
RIFFADS_BASE_URLAnother RiffAds host. You never need ithttps://app.riffads.com
RIFFADS_CONFIG_HOMEFolder for config.json~/.riffads
NO_COLORAny non-empty value: no color, no spinnerunset
FORCE_COLORAnything but 0: color and spinner on. Beats NO_COLOR and CIunset
CIAnything but empty, 0 or false: no spinnerunset

CI

Skip login. Put the key in RIFFADS_API_KEY from your CI secret store, then check it.

CI
riffads whoami   # free; exits 3 if the key or workspace is wrong

Full script: CI script.

Sign out and rotate

Terminal
riffads logout
  • logout deletes the saved file and always exits 0. The key still works until you revoke it on the API keys page.
  • To rotate: create a new key, run riffads login and riffads whoami, then revoke the old key.

Troubleshooting

Errors print on stderr as error: <message> (<code>).

Message starts withExitWhat to do
No RiffAds API key.3Run riffads login, or set RIFFADS_API_KEY
No key given.2Run login at a terminal, or pipe the key in
This RiffAds API key is not valid.3Wrong key. Create a new one
This RiffAds API key has been revoked.3Create a new key
This RiffAds API key was not given the ... scope3Create a key with the scope it names: Generate or Workflows
This workspace's plan does not include the agent API.3Move to a plan that includes it (required_plan)
The workspace this RiffAds API key belongs to is no longer available.3Create a key in a live workspace
This RiffAds API key is sending requests too quickly.5Wait, then retry
Could not reach ...5Check the network and RIFFADS_BASE_URL
... did not answer as a RiffAds API endpoint., "..." is not a valid base URL.2Wrong host. Unset RIFFADS_BASE_URL and --base-url
The RiffAds CLI hit an unexpected problem: ...1Update to riffads 0.3.0 or newer. Older versions fail on the current API

All codes: Errors and Exit codes.

On this page