Setup
Install the riffads CLI, sign in, and make your first video.
Read as MarkdownInstall riffads, give it an API key, and make one video from your terminal.
You need
- Node 20.10.0 or newer, and
jqfor 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
npm install -g riffads
# or run it without installing
npx riffads@latest --versionThe 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
riffads loginlogin 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:
| Order | Source | Notes |
|---|---|---|
| 1 | --api-key <key> | Lands in shell history. Avoid it |
| 2 | RIFFADS_API_KEY | The environment variable |
| 3 | stdin, when piped | pass show riffads/ci | riffads login |
| 4 | Hidden prompt | Terminal only, so CI never hangs |
- Every other command reads
--api-key, thenRIFFADS_API_KEY, then the saved key. An empty value counts as not set. - The key is saved in
~/.riffads/config.jsonwith mode 0600.
Check it
riffads whoamihost https://app.riffads.com (from default)
key ****a91f (from file)
credits 4,200 creditsDoes 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:
{
"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:
# 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 ./outgeneratewaits, then saves<generation-id>-0.mp4in./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 capabilitieslists every one you can run.
Why --max-credits takes the estimate's max_credits_needed, not the bare price: Price first.
Environment variables
| Variable | Effect | Default |
|---|---|---|
RIFFADS_API_KEY | The key. Beats the saved one | none |
RIFFADS_BASE_URL | Another RiffAds host. You never need it | https://app.riffads.com |
RIFFADS_CONFIG_HOME | Folder for config.json | ~/.riffads |
NO_COLOR | Any non-empty value: no color, no spinner | unset |
FORCE_COLOR | Anything but 0: color and spinner on. Beats NO_COLOR and CI | unset |
CI | Anything but empty, 0 or false: no spinner | unset |
CI
Skip login. Put the key in RIFFADS_API_KEY from your CI secret store, then check it.
riffads whoami # free; exits 3 if the key or workspace is wrongFull script: CI script.
Sign out and rotate
riffads logoutlogoutdeletes 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 loginandriffads whoami, then revoke the old key.
Troubleshooting
Errors print on stderr as error: <message> (<code>).
| Message starts with | Exit | What to do |
|---|---|---|
No RiffAds API key. | 3 | Run riffads login, or set RIFFADS_API_KEY |
No key given. | 2 | Run login at a terminal, or pipe the key in |
This RiffAds API key is not valid. | 3 | Wrong key. Create a new one |
This RiffAds API key has been revoked. | 3 | Create a new key |
This RiffAds API key was not given the ... scope | 3 | Create a key with the scope it names: Generate or Workflows |
This workspace's plan does not include the agent API. | 3 | Move to a plan that includes it (required_plan) |
The workspace this RiffAds API key belongs to is no longer available. | 3 | Create a key in a live workspace |
This RiffAds API key is sending requests too quickly. | 5 | Wait, then retry |
Could not reach ... | 5 | Check the network and RIFFADS_BASE_URL |
... did not answer as a RiffAds API endpoint., "..." is not a valid base URL. | 2 | Wrong host. Unset RIFFADS_BASE_URL and --base-url |
The RiffAds CLI hit an unexpected problem: ... | 1 | Update to riffads 0.3.0 or newer. Older versions fail on the current API |
All codes: Errors and Exit codes.