# CLI command reference

> Canonical HTML: https://screenrig.ai/docs/cli

The screenRIG CLI publishes media, playlists and applications to TVs and kiosks from a terminal or an agent. Find the commands, parameters, JSON output, and revision rules for publishing content and operating screens.

## Bundled CLI surface

Commands are grouped the way the CLI groups them. Installation and first use
are covered in [Quickstart](https://screenrig.ai/docs/start.md); the choice
between upload, cards and selectors is covered in [Compose](https://screenrig.ai/docs/compose.md).

| Group | Commands | What it covers |
| --- | --- | --- |
| [Projects](https://screenrig.ai/docs/cli/projects.md) | `project`, `organization`, `invitations`, `agent`, `login`, `billing`, `doctor` | Create, select, rename, move and export projects, sign in and out, invite people, read plan limits and advertising amounts, and run doctor. |
| [Service clients](https://screenrig.ai/docs/cli/service-clients.md) | `service-client` | Create service clients, add and remove their keys and secrets, and revoke them: the sign-in for servers, scripts and CI jobs. |
| [Help and support](https://screenrig.ai/docs/cli/help.md) | `help`, `status`, `docs`, `recovery`, `support`, `feedback` | Search the documentation, check service status, recover from a write with an unknown outcome, talk to support and send bug reports or requests. |
| [Media](https://screenrig.ai/docs/cli/media.md) | `media`, `media folder` | Upload, replace, version, tag, move and delete images, video and audio, with folders, dynamic selectors and availability rules. |
| [Media sync](https://screenrig.ai/docs/cli/media-sync.md) | `media sync`, `media sync account` | Keep a media folder in step with SharePoint, OneDrive, Dropbox or Google Drive: add accounts, create syncs, run them and read their results. |
| [Playlists](https://screenrig.ai/docs/cli/playlists.md) | `playlist` | Prepare, validate, create, patch, export and import playlists, manage their pages, revisions and instances, and replace an application release. |
| [Cards](https://screenrig.ai/docs/cli/cards.md) | `card`, `cards`, `kv webhook` | Find card types, create a card, set its parameters and live data, preview it and update its data from outside systems through signed webhooks. |
| [Applications](https://screenrig.ai/docs/cli/applications.md) | `app`, `kv`, `kv webhook` | Pack, upload, update and delete web applications, and read or write their key/value store and its webhooks. |
| [Screens](https://screenrig.ai/docs/cli/screens.md) | `screen`, `browser setup` | Pair, list, publish to, assign, tag, move, reload, capture and delete screens, and manage folders, links, video walls and live view. |
| [Schedules](https://screenrig.ai/docs/cli/schedules.md) | `screen schedule`, `screen takeover`, `schedule import` | Set, preview, restore and clear a screen's playlist schedule, take screens over for a while and import schedules from a sheet. |
| [Campaigns](https://screenrig.ai/docs/cli/campaigns.md) | `campaign` | Create, preview, publish, promote, pause and restore campaigns that switch a whole audience of screens to a playlist while their rules hold. |
| [Device health](https://screenrig.ai/docs/cli/device.md) | `screen reboot`, `screen display`, `screen brightness`, `screen uptime` | Reboot, restart and update a device, schedule its display and reboots, set brightness, lock the kiosk and read uptime, health and storage. |
| [Reviews and notes](https://screenrig.ai/docs/cli/reviews.md) | `reviews`, `comment`, `notes` | List, show and withdraw reviews of agent changes, attach comments to screens and playlists and leave project notes for later sessions. |
| [Notifications](https://screenrig.ai/docs/cli/notifications.md) | `notifications`, `webhooks`, `alerts`, `events`, `operations` | Tell people and systems when a screen changes state with notifications and webhooks, follow the event log, work alerts and wait on operations. |
| [Reports](https://screenrig.ai/docs/cli/reports.md) | `reports`, `audit`, `playback` | Build reports and schedule them by email, read and verify the audit log, and query playback evidence: plays, totals and completeness. |
| [Data sources](https://screenrig.ai/docs/cli/data-sources.md) | `feeds`, `source`, `connection` | Read third-party feeds, keep a card current from an outside address on a schedule and save Microsoft and Google connections. |
| [BI dashboards](https://screenrig.ai/docs/cli/bi.md) | `bi connection`, `bi view` | Connect Grafana, Tableau, Power BI or a web dashboard, then browse, create, test and show its views on screens. |
| [Triggers](https://screenrig.ai/docs/cli/triggers.md) | `triggers` | Take screens over from CAP emergency alerts and show overlays posted by Home Assistant, sensors or any HTTP client: create, test and rotate triggers. |
| [Fleet links](https://screenrig.ai/docs/cli/fleet-links.md) | `fleet-links`, `migrate` | Create fleet links for device managers and move another signage platform's media, playlists, schedules and screens into screenRIG. |
| [Advertising](https://screenrig.ai/docs/cli/ads.md) | `ads` | Buy ads in a network that invited you or sell ad breaks on your screens: networks, inventory, slots, creatives, campaigns, reviews and reports. |

## Every command runs the same way

```console
screenrig [--json | --human] [--api-url URL] [--config PATH] [--request-id ID]
      [--project-id ID] [--idempotency-key KEY] [--timeout MS] <command> [args]
```

### Global flags

| Flag | Type | Default | Notes |
| --- | --- | --- | --- |
| `--json` | boolean | JSON for operations | Explicit JSON output, retained for compatibility. Also selects structured help. Cannot be combined with `--human`. |
| `--human` | boolean | off | Select human-readable operational output. Cannot be combined with `--json`. |
| `--project-id ID` | string | last-used project | Fix this invocation to a cached project without changing the selection. Each command keeps its target and recovery state for its full run. |
| `--api-url URL` | string | `https://api.screenrig.ai` | Control-plane origin. `SCREENRIG_API_URL` sets the same thing. |
| `--config PATH` | path | the user configuration file | Use a specific configuration file. `SCREENRIG_CONFIG` sets the same thing. |
| `--request-id ID` | string | generated per run | Your own request id: `req_` plus 16 to 64 letters, digits, `_` or `-`. It goes on the first request only and is echoed back as `request_id`. Keep it in reports. |
| `--idempotency-key KEY` | string | derived per write | Reuse the same key to retry an ambiguous write. The server returns the original result for twenty-four hours; a different body under the same key is `idempotency_mismatch`. |
| `--timeout MS` | integer | 30000 per request | Bounds each HTTP request. On a command that waits for an operation it is the wait deadline instead, and the default is 120000. |
| `--help`, `-h` | boolean | off | Print focused help for the command or group and exit. Add `--json` for structured help. |
| `--version`, `-V` | boolean | off | Print the bundled CLI version and exit. Same as the `version` command. |

### Environment

| Variable | Effect |
| --- | --- |
| `SCREENRIG_API_URL` | Control-plane origin, overriding the stored configuration. |
| `SCREENRIG_CONFIG` | Path to the configuration file. |
| `XDG_CONFIG_HOME` | Base of the configuration directory. Otherwise `%APPDATA%\screenrig` on Windows, or `~/.config/screenrig`. |
| `SCREENRIG_FFMPEG` | Absolute path to `ffmpeg`, when `media upload` should not take it from `PATH`. |
| `SCREENRIG_FFPROBE` | Absolute path to `ffprobe`. |
| `SCREENRIG_CWEBP` | Absolute path to `cwebp`, the fallback still encoder. |

None of these is a credential: there is no token flag and no credential
environment variable. The CLI reads the session the plugin stored for this
installation, in a user-private file that survives a plugin upgrade, and renews
it on its own. A configuration saved with `screenrig login --client-id` signs in
as that [service client](https://screenrig.ai/docs/service-clients.md) instead,
reading its key or secret file each time and keeping the token in memory.

### Output

Operational commands write JSON to stdout by default, including errors. A
single result carries an envelope: `ok`, then `data`, `request_id`,
`operation_id`, and `warnings[]` on success, or `error` on failure. Progress,
safe URLs, and human notes go to stderr. `events follow` emits NDJSON: one JSON
envelope per event, on its own line. Redirecting stdout does not change the
format.

Use `--human` for manual inspection. Event commands then print one logfmt line
per event. Help and bare command groups remain readable text by default; use
`screenrig --json playlist --help` for structured discovery. `--json` and
`--human` cannot be combined.

Older plugin bundles may require explicit `--json` for operational results.
Check the installed CLI's help when working with an older bundle.
Playlist authoring files remain JSON documents; a command result
envelope is not an editable playlist document.

An error envelope carries `error.status`, a stable `error.code`, and often
`error.next.command` naming exactly what to run next. Branch on those rather
than on prose.

A change that waits for a person's review is a success, not an error: `ok:
true`, exit `0`, `data.status: pending_review` with the `review`, a
`pending_review` warning naming the review URL, and `data.next` pointing at
`reviews show ID`. A retag of approved media under review is `ok`, exit `0`,
with warning `media_review_pending` instead: its review appears in
`reviews list` within a few seconds. See
[Reviews](https://screenrig.ai/docs/cli/reviews.md#reviews).

### Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success. |
| `1` | Unexpected failure. |
| `2` | Usage error. Nothing was sent. |
| `3` | Credential problem. This installation cannot authenticate. |
| `4` | Not found. |
| `5` | Conflict. |
| `6` | Precondition failed, including `revision_conflict`: the `--expect-rev` revision was stale. |
| `7` | Rate limited. Honor `Retry-After`, surfaced as `retry_after_seconds`. |
| `8` | Other client-side rejection. |
| `9` | Server error. |
| `10` | Network failure. |
| `11` | Timed out. |
| `12` | Configuration error. |
| `13` | The operation itself failed. |

Common problem codes in the envelope:

| Code | Meaning | Next step |
| --- | --- | --- |
| `not_enrolled` | This installation holds no project credential yet. | Create a project with `screenrig agent enroll --email ADDRESS --organization "NAME"`. Use `screenrig login` only when the user asks to use an account that already exists. |
| `session_ended` | The sign-in was revoked, expired or ended. | `screenrig login`, approved by a person in the dashboard. |
| `insufficient_access` | The session's access level cannot do this: Read only changes nothing, and Propose cannot delete, control screens or spend. | `screenrig agent status` shows `effective_access`. When `access_limited_by` names `project` or `person`, the project owner changes the review setting; otherwise `screenrig login --access manage`, approved by a person. |
| `approver_required` | Only the project owner or a member who can approve may do this, such as giving an agent Manage. | Ask the project owner to turn on Can approve, or choose Read only or Propose. |
| `playlist_not_approved` | The playlist has no approved version yet, so no screen can show it. | Wait for its review (`screenrig reviews show ID`), or choose an approved playlist. |
| `review_not_pending` | The review was already decided, withdrawn or replaced. | `screenrig reviews show ID` for its state. |
| `login_denied`, `login_expired` | The person denied the sign-in, or its 24-hour code expired. | Run `screenrig login` again. |
| `client_auth_failed` | A service client's key, secret or id was refused. | Check the key or secret file the config signs in with (`login --client-id ID --client-key-file FILE` or `--client-secret-file FILE`) against `screenrig service-client show ID`. |
| `capability_required` | The project lacks the capability this command needs, such as `screens` or `advertiser`. | `screenrig project capabilities`, then choose the matching `--intent` for a new project or change the project's purpose. |
| `rate_limited` | Too many requests in the current window. | Wait for `retry_after_seconds`, then retry. |
| `free_organization_limit` | The person already holds their free Standard organization, so `project create` cannot start another. | Add the project to the organization the detail names: `screenrig project create NAME --organization-id ID`. Another organization needs Plus, Premium or Enterprise through the contact form at https://screenrig.ai/contact#message. |
| `organization_plan_required` | The organization admits no new screens until a plan pays for it. | The owner moves the project with `screenrig project moves` and `screenrig project move --organization-id ID`, or the organization gets Plus, Premium or Enterprise through the contact form at https://screenrig.ai/contact#message. |

### Revisions and retries

Revision guards are optional. Omit `--expect-rev` to write the current resource
without a prior revision read. Supply it with a known `revision` to reject stale writes. On `revision_conflict`, refetch the
resource, reapply the change, and retry with the returned revision. On an
ambiguous transport failure, retry with the same `--idempotency-key`; the
control plane returns the original result rather than writing twice.

### Agent request cap

An organization's agents, CLI sessions and service clients make up to 500 requests an hour on Standard and Plus, 2,000 on Premium and Education and 10,000 on Enterprise, across all its projects. Nothing is charged. Past the cap a command fails with `rate_limited` and `retry_after_seconds`: wait that long, then retry once. Screens keep playing and the dashboard keeps working.

Each API call a command makes is one request. A fleet command, `screen assign` or `screen tag` with several screen ids or `--tag`, is one request however many screens it reaches, and `screen screenshot --tag` makes one request for each list page it follows. Each JSON page of `playback plays` or `playback list` is one request, and a playback CSV, XLSX or PDF export is one request for its whole range.

These do not count: `project show`, `agent status`, `billing`, `notes list`, `notes show`, `operations wait`, `events follow` and its replay, the screen messages `screen reload`, `screen toast`, `screen identify`, `screen play-page`, `screen screenshot` and `screen live`, [notification](https://screenrig.ai/docs/cli/notifications.md#notifications) emails, screen notices and webhook deliveries, and card data and key/value writes, which keep their own limit.

## Prepare, publish, and edit playlists

For ready images and videos, prepare a full-screen playlist in playback order:

```sh
screenrig playlist init med_POSTER med_VIDEO --name "Lobby loop" --screen-id scr_LOBBY --output lobby.json
screenrig playlist validate lobby.json
screenrig screen publish scr_LOBBY lobby.json
screenrig screen screenshot scr_LOBBY
```

Validate the document, publish it, then look at the real screen with `screen screenshot`. `playlist init` accepts local
image, video and audio files, ready `med_` IDs, pinned `rel_` application releases, HTTP
or HTTPS iframe URLs and pasted `<iframe>` embed codes in playback order, including mixed inputs:

```sh
screenrig playlist init ./poster.png med_VIDEO rel_APP https://example.com --name Lobby --screen-id scr_LOBBY --output lobby.json
```

Local files upload through the normal media path, up to four at a time, and wait
for readiness. This requires ffmpeg and ffprobe unless `--no-transcode` is
supplied. `data.uploads` lists each file's `source`, `media_id`, `reused`, and per-stage
`timing`. Audio files and ready audio `med_` IDs become the soundtrack, in input order, instead of pages. Preparation writes the local document and may upload media; it neither
creates a remote playlist nor assigns a screen. Existing media must be ready.
HTTP and HTTPS URLs may include LAN hosts and embedded credentials and are not
fetched during preparation. A pasted `<iframe>` embed code is read for its `src` and becomes an iframe page. The Player web app requires HTTPS URLs without a
username or password.

If preparation is interrupted, rerun the identical command. Nothing is written
until every upload is ready, so no output file blocks the retry, and a file
whose upload already finished returns its existing media ID (`reused: true`)
instead of uploading again.

Each input except audio becomes one full-screen page with a black background and a 200 ms
crossfade. Images and videos use `--fit contain|cover|fill` (default `contain`).
Videos are silent unless `--sound` is given, do not loop, and advance on completion. Other pages use
`--duration-ms` (default 8000), and an application page holds for 24 hours (86400000 ms) unless it is given. Applications and iframes use `fill`; application
releases are pinned with timed advancement and no controller privileges. Edit the
document for application-controlled advancement. Verify release readiness and actual
playback through the server and intended Player. Publishing can inspect the response headers of eligible public HTTPS iframe pages. A page whose `X-Frame-Options` or `frame-ancestors` refuses framing cannot be shown by the Player web app or the macOS, Samsung Tizen, LG webOS and BrightSign Players. When publishing detects a refusal, the write still succeeds: `screen publish` and playlist writes such as `playlist create|update|patch` print an `iframe_framing_refused` warning naming the page and primitive, and `events list` shows a `playlist.iframe_framing_refused` warning.

Supply `--screen-id` to read the target dimensions and revision. The result includes
`data.screen_id`, `data.screen_revision`, and `data.publish.argv`.
Pass this argument array to the bundled `screenrig` launcher without shell
splitting: it preserves paths, config, and API origin.
Add `--expect-rev` explicitly to guard against later screen changes. Target metadata stays outside the authored document. A screen with a video wall gives its wall's canvas and the matching `format`.

To override the canvas, supply both `--target-width` and `--target-height`. These
also work without a screen, in which case no publish arguments are returned.
Unknown or multiple reported surfaces require explicit dimensions. Output files are exclusive by default; use `--overwrite` to replace an existing authoring file atomically. An empty file does not count as existing. Parent directories are created automatically. URL and release-ID inputs with explicit dimensions work without login.

`screen publish <screen-id> <file>` creates a new playlist, assigns it with an optional **screen** revision guard, reads back the assignment, and waits for the Player to show it. It does not update an
existing playlist by name. Display names may repeat; use the playlist ID for an explicit `playlist update`. Its JSON result reports `playlist_id`,
`playlist_revision`, `screen_id`, `screen_revision`, `stage`,
`assignment_verified`, `playback_verified`, and `playback`.

The wait is bounded by `--timeout` (default 120000 ms) and polls every `--poll-ms` (default 2000 ms). It ends as soon as the
Player acknowledges the playlist on glass: `stage` is `playing` and
`playback_verified` is `true`. Otherwise `stage` stays `assigned` and
`playback.reason`, repeated as a warning code with its next step, says why:

| `playback.reason` | Meaning |
|---|---|
| `screen_offline` | No Player is connected; it plays when the Player reconnects. |
| `playlist_not_effective` | A takeover, campaign or schedule shows `playback.effective_playlist_id`; the published default plays when that ends. |
| `playback_failed` | The Player reported a failed upgrade; `playback.code` names the cause. |
| `playback_pending` | The wait ran out while downloading or preparing (`playback.state`). |
| `not_waited` | `--no-wait` returned after assignment without waiting. |

A `playback_partial` warning means the playlist plays without
`playback.missing_page_count` pages that do not fit the Player's storage.

When the project requires review for agent changes, or the session has Propose
access, `screen publish` stops once the playlist or its assignment is
proposed: `stage` is `pending_review`, the result names both reviews, and the
envelope stays `ok: true`. Nothing plays until a person approves. Add
`--note TEXT` to tell the reviewer what changed; see
[Reviews](https://screenrig.ai/docs/cli/reviews.md#reviews).
Rerunning the identical publish waits again and never creates another playlist.
`--no-wait` returns after assignment. While an `iframe` page shows, a screenshot of the Player web app is `screenshot_unavailable` (`unsupported_surface`); an application page is captured as the application renders itself.

Publishing saves a private local journal automatically. After an ambiguous failure,
repeat the identical command and input with the same config to resume. If playlist
creation succeeded before assignment failed, the error identifies the created
playlist. Do not delete it or start another create to recover. A revision conflict
requires inspecting the screen and reconciling the intended assignment; an already
created playlist can be assigned explicitly with `screen assign`. Publishing never
silently refreshes the expected revision. Unfinished recovery stops after the
24-hour server idempotency window; inspect and reconcile before making more writes.

To edit an existing playlist:

```sh
screenrig playlist show pl_EXISTING --output lobby.json
screenrig playlist update pl_EXISTING lobby.json
```

`playlist show --output` writes the editable document, `{name, pages}` plus the `audio`, `format` and `fields` the playlist has, and returns
its path, `playlist_id`, and source `revision` on stdout. Optionally pass that revision with `--expect-rev` to guard the update. It preserves dynamic selectors, schedules, motion, and pinned
application releases, removing server-derived and read-only fields, so the file
validates and updates as written. Comments remain separate; page comments carry
over by page ID. Plain `playlist show` is an inspection response; `--editable`
without `--output` returns `data.document`, `data.playlist_id`, and `data.revision`.
Updating a playlist affects every screen assigned to it. Under review,
`playlist update` proposes the new document, and `playlist show` keeps
returning the live version until a person approves it. To change part of a playlist, use `playlist rename`, `playlist patch` or `playlist page add|replace|remove`, which send only what changes.

K/V and comment writes accept `--file -` for stdin. Use `playlist show ID --editable --human` for the editable document on stdout. Application and playlist display names may repeat; use resource IDs for updates.

### Replace one application release

After a successful `app update`, take `data.application.release_id` and identify the
exact playlist, page, and application primitive to change. Preview the replacement:

```sh
screenrig playlist replace-release pl_EXISTING --page board-page --primitive board --release-id rel_NEW
```

This is a read-only impact review. Inspect
`data.previous_release_id`, `data.release_id`, and `data.affected_screens`, including
archived assignments. Apply directly with `--apply`. To opt into this impact check, also supply `--expect-impact` with the preview’s `data.impact`:

```sh
screenrig playlist replace-release pl_EXISTING --page board-page --primitive board --release-id rel_NEW --apply
```

Other primitives and settings are preserved. The update affects every screen
assigned to this shared playlist; archived screens retain the new pin for later
use. When `--expect-impact` is supplied, a changed replacement, revision, or observed screen impact requires a fresh preview. Direct apply skips the screen survey; `affected_screens` is omitted. An already pinned release succeeds without writing. Assignments may change after the snapshot: the server checks the playlist revision atomically only when `--expect-rev` is supplied. The server validates release
availability and ownership on apply. Existing pins remain unchanged until apply;
afterward, verify manifest revisions and playback on the affected screens.
Under review, `--apply` proposes the new pin; add `--note TEXT` for the
reviewer.

`playlist validate`, `create`, `update` and `patch`, and `screen publish`, accept `-` as their
input file to read stdin, and `playlist page add|replace` accept `--file -`. JSON envelopes are never written into authored files.
`--expect-rev` guards a revision. Omit the flag to write the current resource without a revision precondition. A supplied stale revision still returns `revision_conflict`.


### Command names and discovery

Use `show` to inspect a resource, `list` for collections, and `kv get` / `kv set`
for values. Use `--name` for display names, `--screen-id`, `--app-id`,
`--playlist-id`, and `--release-id` for resource selectors, `--expect-rev` for
revision guards, and `--after` for event cursors. The group is `app`; “application”
is the resource name. Comments keep `comment ACTION screen|playlist ID`.

Use `screenrig help --all` for the full inventory or `screenrig playlist init
--help` for focused help. Add `--json` for argument metadata, choices, defaults,
examples, and option relationships. `exactlyOne`, `atLeastOne`, `atMostOne`, and
`together` groups are checked before configuration or network access; `requires`
means the first option requires all remaining options. Read stdin only where
command help explicitly supports `-`.

### Create a new project

```sh
screenrig agent enroll --email ADDRESS --organization "NAME"
```

`agent enroll` creates an identity, organization, project and membership, and stores identity and project credentials privately. Name the organization after the business the screens are for, else the person, as you know them from the conversation. Pass Screens only when you know neither, and screenRIG names the organization from the email address. The project gets a readable two-word name the person can rename. `--organization` is required; `--name`, at most 80 characters, separately names the agent.
Use the person's actual contact email. Enrollment emails a project-member
invitation; it does not disclose whether that address already has a login.
The person opens the invitation and creates a login with a passkey,
or signs in to add the project to their existing login.
Acceptance moves the project into the organization holding the person's
verified email domain, otherwise into the free Standard organization they
already hold, renamed on a name clash.

Add `--intent advertising` for a project that buys ads rather than pairing
screens. `--setup-code CODE` links the new project to the website visit that showed the code, such as `K7QX-2MPD`. `--force` replaces this installation's enrollment or pending connection
state when intentionally creating another project.

```console
agent enroll (--email ADDRESS | --agentid-claim CODE) --organization NAME [--name NAME]
    [--intent signage|advertising] [--setup-code CODE] [--force]
```

### Sign in with AgentID

An agent with an AgentID signs in at https://api.screenrig.ai/agentid/start,
receives a claim code, installs the official plugin, and runs `screenrig agent
enroll --agentid-claim CODE --organization "NAME"`. The owner's verified email
receives the dashboard invitation.

<a id="sign-in"></a>

### Sign in to an existing account

```sh
screenrig login
```

`login` signs this installation in to an account that already exists. It
prints a dashboard address and a code, then waits up to 24 hours. A person
opens the address, which carries the code, checks that it matches, adjusts the
project, **Read only**, **Propose** or **Manage**, or the capability areas if they
want, and presses Connect once; a dashboard sign-in from the last hour is the
proof, so there is no second passkey prompt. The CLI stores
the session, selects the approved project and returns `status: signed_in` with
the project, organization and `access`.

```console
login [--project ID] [--access read|propose|manage] [--name NAME] [--no-wait] [--resume ID]
login --client-id ID (--client-key-file PATH | --client-secret-file PATH)
logout
```

`--access` asks for a level; the default is `manage`, and the person decides.
`--project` suggests the project. `--no-wait` returns `status: pending` with
the `verification_uri_complete`, the `user_code` and a `login_` handle that
holds no secret; `login --resume ID` waits for the approval later. Run `login`
again on a signed-in installation to add another project or to raise a Read
only or Propose project to Manage.

Each session carries capability areas: `screens`, `content`, `playlists`,
`advertising`, `reports`, and `project`. A session calls only commands in its
areas; `reports` also reads any area. A command outside them returns `403
forbidden` with detail `This agent credential lacks the <name> capability.`
Read only sessions list and read. Propose sessions also upload media, write
notes and propose media, playlist and screen changes, which wait for a
person's [review](https://screenrig.ai/docs/cli/reviews.md#reviews). A change beyond the
session's level returns `403 insufficient_access`.

`logout` revokes the sign-in on the server and removes the stored tokens; in a service client's configuration it removes the saved client. A
failure that might not have reached the server keeps them, so rerunning
`logout` is safe. `doctor` shows when the session ends: 90 days after its last
use, and at most one year after sign-in. See
[Authentication](https://screenrig.ai/docs/authentication.md).

## Keep the path short

- [Start with the official plugin](https://screenrig.ai/docs/start.md)
- [Open a Player](https://screenrig.ai/docs/players.md)
- [Choose an authoring path](https://screenrig.ai/docs/compose.md)
- [Install the official plugin](https://github.com/screenrig/plugin)
- [See features](https://screenrig.ai/features.md)

The bundled CLI uses `api.screenrig.ai`; Players use `play.screenrig.ai`;
the dashboard is at `screenrig.ai/dashboard`; releases use isolated
origins under `apps.screenrig.ai`. Application packages reach native Players
through private, server-mediated delivery. The
[internal transport reference](https://screenrig.ai/docs/api.md) remains available for transport tooling.
