# CLI

> Log in, build a brief from a diff, run productions and manage webhooks from a terminal.

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 raylight

raylight 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](https://www.raylight.app/docs/authentication.md): 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.json

raylight 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](https://www.raylight.app/docs/productions.md).

## 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](https://www.raylight.app/docs/webhooks.md).

## 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](https://www.raylight.app/docs/github-action.md) wraps the same steps and posts the pitch as a check.

## More

- Previous: [GitHub Action](https://www.raylight.app/docs/github-action.md)
- Next: [Recipes](https://www.raylight.app/docs/recipes.md)
- All docs: https://www.raylight.app/llms.txt
- Everything in one file: https://www.raylight.app/llms-full.txt
- OpenAPI: https://api.raylight.app/v1/openapi.json