Automate

CLI

The REST API for a terminal, with the brief built on your machine. Run it from a checkout, or in CI when the GitHub Action does not fit.

Install and log in

bash

npm install -g raylightraylight login

That puts raylight on your path. To run it without installing, put npx in front of every command instead (npx raylight login, npx raylight productions create ...).

login runs the device flow: open the printed URL, click Approve, and the key is saved locally together with the server it was made on. The key and server travel as a pair: a saved key is only ever sent to its own server, and if --api-url or RAYLIGHT_API_URL points somewhere else the CLI refuses and tells you to log in there. Servers must be https, except localhost for local development. raylight whoami shows which key and server commands would use and where each comes from, without a network call. raylight logout revokes the key on the server, then deletes the local copy (--keep-key only deletes it). When running unattended, set RAYLIGHT_API_KEY instead; it wins over the saved key.

Make a video

bash

raylight productions create \  --intent "Announce dark mode in the Acme dashboard to existing customers." \  --code "src/**/*.tsx"raylight productions greenlight 6f1c2b7e-3d4a-4c8e-9a2b-1f0e5d6c7b8a

productions create pushes a brief to start a production. --intent is the one sentence; --code takes globs and reads the matching files from the working tree. --greenlight-mode auto greenlights a video verdict as soon as the pitch lands, and --external-id makes a retried create return the same production.
productions create and productions comment wait for the pitch and print it (title, shots, price). Pass --no-wait to print the production's id and return right away, for example in CI.
productions greenlight <id> greenlights the pitch. It charges the price the pitch quoted (60 credits per second of video) once; --pitch-version <n> refuses if the pitch changed since you read it.
productions comment <id> --comment "..." sends comments and waits for the next version. It takes --pitch-version too.
productions get <id>, productions list (--external-id finds the production a create made), productions decline <id>, productions cancel <id> and productions usage map one to one onto the API.
productions watch <id> follows a production until it ends, printing each stage as the app labels it.

Exit codes

Every command exits nonzero when it did not get what it waited for, so a CI step fails instead of passing quietly. --json prints machine readable output either way.

Code	Means
0	Done.
1	Failed: bad flags, not logged in, refused by the server, or a network error.
2	The production ended without what the command waited for: it failed, was declined, cancelled or skipped, or your comments were refused (for example the monthly cap). `watch` exits 0 only once the production wrapped.
3	Timed out while the production was still going.
130	Stopped with Ctrl-C.

Build a brief from a diff

brief build walks a diff, keeps the UI source files, and computes each file's change status, line counts, patch, a digest of how the UI looks, and a relevance score. It writes a brief you can inspect before anything is sent.

bash

raylight brief build --diff main..HEAD --out brief.jsonraylight productions create --brief brief.json

brief.json is everything that leaves your machine. Edit it, drop files, add media URLs or a brand, then productions create --brief brief.json. Ranking rules are on Productions.

Webhooks

bash

raylight webhooks create --url https://hooks.acme.dev/raylight

Prints the endpoint and its secret once. webhooks list, webhooks test <id> and webhooks deliveries <id> cover the rest of the webhooks surface.

In CI

Any CI works: add RAYLIGHT_API_KEY to the job's secrets, check out full history so brief build --diff has both sides, and run the two commands with --no-wait if the step should not hold the runner while the pitch is written. On GitHub the Action wraps the same steps and posts the pitch as a check.