rgba CLI

HTTPS client for the deployed RGBA API, plus a literal local Remotion wrapper. The API defaults to the right backend URL; override with RGBA_API_URL for local dev. RGBA provides a UI and tools for external agents; it does not run its own agent. For disposable Kubernetes/Modal agent containers, see the production runtime.

Install

pip install rgba             # from PyPI
pipx install rgba            # isolated user install (recommended for daily use)

After install you'll have a rgba command on your PATH.

Usage

rgba auth login              # device-flow → opens https://rgba.ai/cli in your browser
rgba auth status             # show whoami
rgba auth logout             # revoke the active token
rgba install skill --path ./skills/rgba
rgba auth worker-token --label JOB --output /secure/job.json # controller: one expiring credential per job

rgba me --json               # verified identity, machine-readable
rgba doctor --json           # tools, login, live API and Postiz preflight
rgba doctor --offline        # local checks without network calls
rgba actions                 # discover every /sdk/action with cost + params
rgba actions <name>          # full schema for one action
rgba actions query -p table=videos -p status=accepted --summary --json
rgba actions query -p table=videos --fields id,name,status --json
rgba context --video VIDEO --json --summary
rgba actions <action> -p key=val # call /sdk/action (`rgba sdk` is a legacy alias)
rgba jobs get <job_id>       # poll a job
rgba jobs wait <job_id>      # poll until status is completed/failed
rgba actions social-publish -p operation=channels # connected social accounts
rgba actions social-publish --params-file publish.json # draft/post/schedule video

Skill installation downloads the complete prompts and example code/media from RGBA's public S3/CloudFront artifact store; no login is needed. The CLI package contains no example media. --path is the exact directory containing SKILL.md and its resources; no agent-specific directories are added automatically.

rgba install skill --path ./skills/rgba                  # latest stable skill
rgba install skill --path ./skills/rgba --version <sha256> # pin the printed skill version
rgba install skill --path ./skills/rgba --offline         # reuse the last verified release

Skills update independently of the CLI. Downloads are verified with SHA-256 and cached under $XDG_CACHE_HOME/rgba/skills (default ~/.cache/rgba/skills). Unchanged examples are reused when only prompts change. The first install needs networking; --offline requires a complete cached release and never makes network requests.

Updates replace unchanged managed files and remove retired managed files. Locally edited files require --force; unrelated files are preserved. Existing installations from older CLIs have no inventory, so differing files require review and --force on their first update. .rgba-skill.json tracks the installed release and file hashes. Running the install command without arguments shows help.

Credentials live in ~/.rgba/credentials (mode 0600). The CLI never sees your Supabase password — auth is brokered through a device flow against the RGBA backend. Containers use RGBA_CREDENTIALS_FILE (read-only secret) or RGBA_CREDENTIALS_JSON. Use independent worker tokens for concurrent jobs; never share a rotating device-login credential across them. All product writes use ownership-checked RGBA APIs, not a Supabase service key.

Resumable accepted-video publication

python -m rgba_cli uses the console entry point and error handling. doctor is read-only; it never installs, logs in or publishes. --fields aliases --select; projections preserve pagination metadata. --summary omits large source manifests without changing API response contracts.

rgba publish prepare --video VIDEO --plan plan.json --directory EPISODE/publishing validates five native destinations and freezes exact captions/settings and permanent request IDs. rgba publish run EPISODE/publishing publishes and resumes that campaign; rgba publish status EPISODE/publishing --json only reconciles.

See the canonical publishing workflow for complete plan JSON, workspace linking, manual leases and recovery. The plan supplies actual cover/frame observations and audience/AI/branding declarations. Media comes from the accepted video; a TikTok target may supply a hashed local delivery copy. Attempted posts are never retried and legacy ledgers are preserved. Provider delivery, individual permalinks and public verification stay separate. All five provider deliveries and RGBA readback are required for finalization; --no-finalize defers status for the separately guarded Reddit decision. No backend deployment is needed.

Author and render explainers

Read prompts/animation/guide.md for storytelling and production, and prompts/animation/visuals.md for art direction, motion and copied benchmark projects under assets/explainer-animation/. No additional skill is needed. The same coding agent writes real React/Remotion source and iterates on rendered review. RGBA runs the project's installed Remotion CLI and records its workspace; it does not turn the story into a restricted scene format or rewrite the animation. The following local commands require no RGBA login:

rgba install skill --path .agents/skills/rgba
# Read prompts/animation/guide.md and visuals.md in the installed RGBA skill.
rgba explainer scaffold /path/to/new-film --version 4.0.529

rgba remotion --project-dir /path/to/film studio src/index.ts --no-open
rgba remotion --project-dir /path/to/film still src/index.ts Film /tmp/frame.png --frame=120
rgba remotion --project-dir /path/to/film render src/index.ts Film /tmp/film.mp4
rgba remotion --project-dir /path/to/film --help

Only an initial --project-dir DIR or --project-dir=DIR belongs to RGBA. Every following argument is passed unchanged, including unknown/future flags, help, props, browser, bundle, render and Studio commands. An initial -- ends wrapper option parsing explicitly. The wrapper uses no shell, inherits the native environment and terminal streams, and preserves exit status and signals. It uses the installed project dependency rather than silently downloading a different Remotion version. scaffold invokes upstream create-video's blank template in a new or empty directory; the coding agent then authors the film.

Inspect the actual entrypoint and registered compositions:

rgba explainer inspect --project-dir /path/to/film --entry-point src/index.ts \
  --studio-url http://localhost:3417 --output /tmp/film-project.json

The JSON is the project value for explainer-video register/update operations. It includes exact CLI composition metadata, installed package versions, a file manifest with SHA-256 hashes, and a source revision. The revision is SHA-256 of canonical JSON (sort_keys, compact separators, ASCII escaping) containing entrypoint, files, package_versions and compositions. Paths and optional Studio URLs are separate from source identity. Inspect passes additional flags to native composition discovery, so --props and browser configuration work.

Inspection includes public assets and excludes dependency caches, build/output folders and credential files. It rejects source directory symlinks instead of silently omitting their contents, and rejects changes made during inspection. Write snapshots outside the workspace to avoid hashing the snapshot itself. The optional Studio address must use localhost, 127.0.0.1 or ::1 and does not start a server. Composition metadata is captured from the installed CLI's actual discovery result; an unsupported future metadata-adapter layout fails clearly while rgba remotion remains available unchanged.

CPU work in one sandbox or container

Keep Remotion/Chromium rendering, FFmpeg audio processing and clip assembly in the same environment as the installed CLI. The Python wheel does not itself install Node.js, browsers, FFmpeg, fonts or project npm dependencies. Check those tools before rendering:

rgba runtime doctor --project-dir /path/to/film --json
rgba media stitch first.mp4 second.mp4 --output joined.mp4 \
  --width 1920 --height 1080 --fps 30

These commands need no login or API connection. Local stitching normalizes clips with FFmpeg, retains their first audio track and pads missing audio with silence. It supports ordered MP4 assembly; it does not reproduce the hosted editor's timeline effects. rgba actions stitch-video continues to submit a remote API job, so use rgba media stitch for the local CPU workflow.

The container runtime packages the installed wheel, Node, Remotion, Chromium, FFmpeg and fonts. Its smoke test renders animation and sound, then stitches clips with networking disabled. Install/fetch dependencies and assets during setup; account/storage APIs and GPU provider services can remain remote. No secondary CPU render container is required.

Publish videos

Video publishing supports YouTube, Instagram, TikTok, Facebook, Threads, and Pinterest through Postiz (Pinterest also needs a cover_url image per target). promote-video posts link promotions to X, Reddit, and Medium. In RGBA, open Settings → Connect Postiz, save your Postiz workspace API key, and connect your social accounts. Multiple channels are supported. The key stays on the server; do not pass it to the CLI.

Run rgba actions social-publish -p operation=channels to find channel IDs. For a YouTube draft, save this as publish.json with your channel ID and a public HTTPS video file URL:

{
  "operation": "publish",
  "request_id": "my-video-001",
  "video_url": "https://your-cdn.example/video.mp4",
  "mode": "draft",
  "targets": [{
    "channel_id": "YOUR_CHANNEL_ID",
    "content": "My video description",
    "settings": {"title": "My video", "type": "private", "selfDeclaredMadeForKids": "no"}
  }]
}

Then run rgba actions social-publish --params-file publish.json. Local files can first use rgba actions upload -p file_path=/path/video.mp4; use the returned URL. An owned RGBA video's video_id can replace video_url. Publishing defaults to a draft; use mode=now or mode=schedule with a timezone-aware publish_at for authorized automation. Reuse the same request_id and parameters on retries to avoid duplicate submissions. An accepted receipt means Postiz accepted the submission; use operation=posts with start_date and end_date to check delivery. Run rgba actions social-publish for the full action schema.

Environment