Metadata-Version: 2.4
Name: rgba
Version: 0.4.4
Summary: Command-line interface for RGBA — drive the RGBA video-creation API from your terminal or Claude Code.
Author: RGBA
License-Expression: MIT
Project-URL: Homepage, https://rgba.ai
Project-URL: Documentation, https://rgba.ai/docs
Project-URL: Issues, https://rgba.ai/support
Keywords: rgba,ai,video,cli,claude,agent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer<1.0,>=0.12
Requires-Dist: httpx<1.0,>=0.27
Dynamic: license-file

# 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](container/README.md).

## Install

```bash
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

```bash
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 install explainer-skill --path ./skills/codex-explainer
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 is on demand. Each command requires `--path`, the exact
directory that will contain `SKILL.md` and its supporting resources; missing
directories are created. No agent-specific directories are added automatically.
Running either install command without arguments shows help. Identical files are
skipped; differing files require `--force`, and unrelated files are preserved.

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](../.agents/skills/rgba/references/publishing-cli.md)
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

First read `rgba prompts animation/guide`. This self-contained prompt includes the
relevant codex-explainer instructions; 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:

```bash
rgba prompts animation/guide  # read the complete authoring instructions
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:

```bash
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:

```sh
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](container/README.md) 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:

```json
{
  "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

| var              | default                                                                  | use                                       |
|------------------|--------------------------------------------------------------------------|-------------------------------------------|
| `RGBA_API_URL`   | `https://lemontree-media-llc--rgba-api.modal.run`            | Override the API origin (e.g. localhost)  |
| `RGBA_CONFIG_DIR`| `~/.rgba`                                                                | Override credentials directory            |
