# Data sources CLI commands

> Canonical HTML: https://screenrig.ai/docs/cli/data-sources

Read third-party feeds, keep a card current from an outside address on a schedule and save Microsoft and Google connections. Every command here runs as described in the [CLI reference](https://screenrig.ai/docs/cli.md): global flags, JSON output, exit codes, revisions and retries.

## Feeds

A feed is third-party data that screenRIG fetches and caches, such as weather, alerts, rates and headlines. `feeds get` reads one feed document, the same document a built-in card with the same params reads. The command never calls a third-party provider.

### `feeds get`

Read a feed once. A feed with no document yet answers `pending` and its retry time.

```console
feeds get <family> [--lat DEGREES --lon DEGREES] [--radius-km KM] [--min-magnitude N] [--hours N]
                   [--basins LIST] [--base CODE] [--symbols IDS] [--currency CODE] [--url URL]...
                   [--station ID] [--country CODE] [--category drug|food] [--region NAME] [--date YYYY-MM-DD]
                   [--provider tfl|entur|digitransit] [--stops IDS] [--system ID]
                   [--public] [--geocode NAME:VALUE]... [--min-severity LEVEL] [--max-severity LEVEL]
                   [--min-urgency LEVEL] [--min-certainty LEVEL] [--event NAME]... [--exclude-event NAME]...
                   [--sender NAME]... [--status STATUS]... [--scope SCOPE]... [--language TAG]...
                   [--area-unknown hide|show]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<family>` | string | yes | none | `weather`, `airquality`, `alerts`, `rates`, `crypto`, `earthquakes`, `cyclones`, `headlines`, `cap`, `tides`, `launches`, `drugalerts`, `respiratory`, `almanac`, `outdoorsafety`, `departures` or `bikeshare`. |
| `--lat DEGREES` | number | per family | none | Latitude, -90 to 90, with `--lon`. Required for `weather`, `airquality`, `alerts`, `earthquakes`, `outdoorsafety` and `bikeshare`; optional for `cyclones`, `cap`, `tides` and `almanac`. |
| `--lon DEGREES` | number | per family | none | Longitude, -180 to 180, with `--lat`. |
| `--radius-km KM` | number | no | `500` for `earthquakes` | `earthquakes` radius, or the `cyclones` area, from 10 to 20000 km. Requires `--lat` and `--lon`. |
| `--min-magnitude MAGNITUDE` | number | no | `2.5` | `earthquakes`: least magnitude, 0 to 9. |
| `--hours HOURS` | number | no | `24` | `earthquakes`: window in hours, 1 to 168. |
| `--basins LIST` | string | no | all basins | `cyclones`: comma-separated basins `at`, `ep`, `cp`, `wp`. |
| `--base CODE` | string | no | `EUR` | `rates`: base currency. |
| `--symbols IDS` | string | yes, for `crypto` | none | Comma-separated crypto ids or tickers, at most 20. |
| `--currency CODE` | string | no | `usd` | `crypto`: quote currency. |
| `--station ID` | string | no | none | `tides`: a NOAA tide prediction station id of seven letters or digits, such as `9414290`. Without it, `--lat` and `--lon` pick the nearest station within 100 km. |
| `--country CODE` | string | per family | none | `drugalerts`: `us`, `ca` or `gb` (required). `respiratory`: `us` or `gb` (required). `almanac`: the ISO 3166-1 country whose public holidays it lists. |
| `--category CATEGORY` | string | no | `drug` | `drugalerts`: `drug` or `food`. |
| `--region NAME` | string | no | the nation | `respiratory`: a US state, territory or DC by name or postal code, or England or a UKHSA region, at most 48 characters. |
| `--date YYYY-MM-DD` | string | no | the days around today | `almanac`: one fixed day. |
| `--provider PROVIDER` | string | yes, for `departures` | none | `departures`: the transit provider of the stops, `tfl`, `entur` or `digitransit`. |
| `--stops IDS` | string | yes, for `departures` | none | `departures`: one to four stop ids of the provider, comma-separated, such as the TfL StopPoint id `940GZZLUOXC`, the Entur ids `NSR:StopPlace:337` and `NSR:Quay:568`, or the Digitransit gtfsId `HSL:1040129`. |
| `--system ID` | string | no | the nearest system | `bikeshare`: a bike share system id, such as `Mobibikes_CA_Vancouver`. Without it the nearest listed system that covers `--lat` and `--lon` serves. |
| `--url URL` | string | yes, for `headlines` | none | `headlines`: an RSS or Atom feed URL. `cap`: a CAP alert or ATOM/RSS index URL; repeat it, at most 5. |
| `--public` | boolean | no | on without `--url` | `cap`: also read the public alert feeds that cover `--lat` and `--lon`. Requires `--lat` and `--lon`. |
| `--geocode NAME:VALUE` | string | no | none | `cap`: an area code of the location, such as `UGC:WAC033`. Repeatable. Requires `--lat` and `--lon`. |
| `--min-severity LEVEL` | string | no | none | `cap`: only alerts at or above `minor`, `moderate`, `severe` or `extreme`. |
| `--max-severity LEVEL` | string | no | none | `cap`: only alerts at or below `minor`, `moderate`, `severe` or `extreme`. |
| `--min-urgency LEVEL` | string | no | none | `cap`: only alerts at least this urgent: `past`, `future`, `expected` or `immediate`. |
| `--min-certainty LEVEL` | string | no | none | `cap`: only alerts at least this certain: `unlikely`, `possible`, `likely` or `observed`. |
| `--event NAME` | string | no | any event | `cap`: only this event; `*` matches any run of characters. Repeatable. |
| `--exclude-event NAME` | string | no | none | `cap`: leave out this event. Repeatable. |
| `--sender NAME` | string | no | any sender | `cap`: only alerts from this sender. Repeatable. |
| `--status STATUS` | string | no | `Actual` | `cap`: alert status to read: `Actual`, `Exercise`, `Test` or `System`. Repeatable. |
| `--scope SCOPE` | string | no | `Public` | `cap`: alert scope to read: `Public`, `Restricted` or `Private`. Repeatable. |
| `--language TAG` | string | no | `en` for `almanac` | `cap`: language preference; the first present wins. Repeatable. `almanac`: the On This Day edition, one of `ar`, `bs`, `cs`, `de`, `en`, `es`, `fr`, `it`, `pt`, `ru`, `sv`, `tr`, `uk` or `zh`. |
| `--area-unknown MODE` | string | no | `hide` | `cap`: an alert told only by area codes the location lacks: `hide` or `show`. |

```console
screenrig feeds get weather --lat 49.25 --lon -123
screenrig feeds get rates --base EUR
screenrig feeds get crypto --symbols btc,eth --currency usd
screenrig feeds get earthquakes --lat 49.25 --lon -123 --radius-km 500 --min-magnitude 4 --hours 72
screenrig feeds get cyclones --basins at,ep
screenrig feeds get headlines --url https://example.com/news.xml
screenrig feeds get cap --lat 49.25 --lon -123 --geocode UGC:WAC033 --min-severity moderate --event '*warning'
screenrig feeds get cap --url https://example.com/alerts.atom --url https://example.com/other.xml
screenrig feeds get tides --station 9414290
screenrig feeds get drugalerts --country us --category food
screenrig feeds get respiratory --country us --region California
screenrig feeds get almanac --country CA --date 2026-12-25
screenrig feeds get departures --provider tfl --stops 940GZZLUOXC
screenrig feeds get bikeshare --lat 49.25 --lon -123
screenrig feeds get launches
```

`weather`, `airquality`, `alerts`, `earthquakes`, `outdoorsafety` and `bikeshare` need `--lat` and `--lon`, which always go together; `earthquakes` also takes `--radius-km`, `--min-magnitude` and `--hours`, and `bikeshare` takes `--system`. `cyclones` takes `--basins`, and with `--lat`, `--lon` and `--radius-km` together only the storms near that place. `rates` takes `--base`, `crypto` needs `--symbols` and takes `--currency`, and `headlines` needs `--url`. `tides` needs `--station`, or `--lat` and `--lon` for the nearest prediction station. `drugalerts` needs `--country` and takes `--category`, `respiratory` needs `--country` and takes `--region`, and `almanac` takes `--country`, `--language`, `--lat`, `--lon` and `--date`. `departures` needs `--provider` and `--stops`, and `launches` takes no flags. A flag the family does not take is refused. [Built-in cards](https://screenrig.ai/docs/cards.md#feeds) describes each family's data.

`cap` reads the CAP alerts that match a place. It needs `--url` (repeatable, up to 5 CAP alert or ATOM/RSS index URLs) or `--lat` and `--lon`, which read the public feeds covering the location; `--public` adds those public feeds to the `--url` sources. The filter flags mirror the members of a `triggers create --pull` object.

A cached document answers `200` with `fetchedAt` and `attribution`: show the attribution wherever the data shows. With no document yet the envelope reports state `pending`, `retry_after_seconds` and `retry_at` with exit 0; the CLI does not loop, so run the command again after `retry_at`. An organization registers at most 50 new feed keys a day, and `rate_limited` follows past that. Cards derive feed keys from static params; do not write `feed` or `feed:` keys yourself.

## Data sources

A data source reads an outside address on a schedule and writes the result to one card's data, so the card stays current without anyone republishing and screens refetch the document when it changes. The kinds are `ics`, `sheets`, `csv`, `json`, `microsoft365`, `google_calendar`, `square`, `shopify`, `toast` and `momentus`. One source writes one card, and an organization has up to 200 across its projects. A sync that fails never writes: the card keeps its last good document and the source's status shows the error. The settings of each kind, the status codes and the privacy rules are on [Data sources](/docs/sources).

A [preset](https://screenrig.ai/docs/sources.md#start-from-a-preset) is a ready-made, tested `json` source for one service, such as a Slack channel, a job board or a build board: `source presets` lists them, `source presets NAME` shows a preset's fields and secrets, and `source create --preset NAME` makes the source.

Give each credential as `--secret NAME=@FILE`, or `NAME=-` for stdin, so it stays out of your shell history and process list. Secrets are stored sealed and shown back only as a masked hint. The secret names are `calendar_url.KEY` for `ics` (one per calendar), `token` for a `csv` or `json` address that needs one (`password`, `client_secret`, `header.NAME` and `query.NAME` serve its other ways to sign in, described under [Requests, sign-in and pages](https://screenrig.ai/docs/sources.md#requests-sign-in-and-pages)), `client_secret` for `microsoft365` and `toast`, `service_account_key` for `google_calendar`, `access_token` for `square` and `shopify`, `api_key` and `api_secret` for `momentus`, and `client_secret` with the `client_id` setting for a `shopify` app installed on the store.

`--settings` takes the source's whole settings object as JSON, `@FILE` or `-`. `--set KEY=VALUE` sets one top-level member and repeats; the value is JSON when it parses (`days=14`, `calendars='[{"key":"lobby"}]'`) and text otherwise (`time_zone=America/Vancouver`). With both, `--set` members replace the same members of `--settings`; `source update` with only `--set` changes those members of the saved settings. The CLI's own `--config` option names its credential file and has nothing to do with sources.

### `source list`

List the project's data sources, newest first, with their status.

```console
source list [--after CURSOR]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `--after CURSOR` | string | no | first page | The `data.next_cursor` of the previous page. |

```console
screenrig source list
```

### `source show`

Inspect one source: its settings, masked secrets, last run and last error.

```console
source show <source_id>
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<source_id>` | string | yes | none | The source (`src_…`). |

```console
screenrig source show src_01EXAMPLESOURCE000000
```

### `source presets`

List the ready-made source presets, or show one with its fields, secrets and how to get them.

```console
source presets [<name>]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<name>` | string | no | every preset | A preset's name: lower-case words joined by hyphens, such as `slack-channel`. |

```console
screenrig source presets
screenrig source presets slack-channel
```

The list shows each preset's title, the card types it fills (the first is the one it is made for) and its category. A name shows the fields to set (`--set NAME=VALUE`: text with its pattern and an example, a choice, or a list that takes a JSON array), the secrets to enter (`--secret NAME=@FILE`) with where the vendor issues each, how often it refreshes, how long a card keeps its last data, and whose data it reads under which terms. Nothing is created.

### `source create`

Create a source. It runs within seconds and then on its schedule. Create the card first and preview with `source test`.

```console
source create (--kind KIND | --preset NAME) --card CARD_ID --name NAME [--settings JSON|@FILE|-] [--set KEY=VALUE]...
               [--connection-id ID] [--secret NAME=VALUE]... [--refresh DURATION] [--stale-after DURATION|none] [--disabled]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `--kind KIND` | string | without `--preset` | none | `ics`, `sheets`, `csv`, `json`, `microsoft365`, `google_calendar`, `square`, `shopify`, `momentus` or `toast`. |
| `--preset NAME` | string | without `--kind` | none | Make the source from a ready-made, tested preset (`source presets` lists them): `--set` and `--settings` then give the preset's fields and `--secret` its credentials. Not with `--kind`. |
| `--card CARD_ID` | string | yes | none | The card (`crd_…`) the source writes. A card has one source; `source_target_taken` answers a second. |
| `--name NAME` | string | yes | none | 1 to 80 characters. |
| `--settings SETTINGS` | string | no | `{}` | The source's whole settings object as JSON, `@FILE` or `-` for stdin. With `--preset`, the preset's fields. |
| `--connection-id ID` | string | no | none | `microsoft365` and `google_calendar`: read through a project connection (`pcn_…`, `connection list`) instead of a tenant, `client_id` and a secret of the source's own. It sets the `connection_id` setting. Not with `--preset`. |
| `--set KEY=VALUE` | string | no | none | One top-level setting: JSON when the value parses (`days=14`, `calendars='[{"key":"lobby"}]'`), text otherwise (`time_zone=America/Vancouver`). Repeatable. With `--preset`, one field of the preset: the text as written, unless it is a JSON array or object (a list field's items). |
| `--secret NAME=VALUE` | string | no | none | A credential by name: `NAME=@FILE`, `NAME=-` (at most one option reads stdin) or `NAME=VALUE`. Repeatable. With `--preset`, the preset's credentials. |
| `--refresh DURATION` | string | no | by kind | How often to sync, `30s` to `24h`, such as `90s`, `5m` or `1h30m`. The kind sets the default and the shortest: 5 minutes and 1 minute for `ics`, `sheets`, `csv` and `json`; 2 minutes and 1 minute for `microsoft365` and `google_calendar`; 5 minutes and 2 minutes for `square`, `shopify` and `toast`; 1 minute and 30 seconds for `momentus`. A preset sets its own. |
| `--stale-after DURATION` | string | no | by kind | How long the card keeps the last good data when the source cannot refresh, `1m` to `7d`, at least twice `--refresh`; `none` keeps it until the next refresh. After that the data expires on every screen. `momentus` defaults to `30m`, and a preset sets its own. |
| `--disabled` | boolean | no | off | Create the source stopped; nothing is fetched until `source update --enable`. |

```console
screenrig source create --kind ics --card crd_01EXAMPLECARD000000000 --name "Lobby calendar" --set calendars='[{"key":"lobby"}]' --set time_zone=America/Vancouver --secret calendar_url.lobby=@lobby.url
screenrig source create --kind sheets --card crd_01EXAMPLEMENU0000000000 --name "Cafe menu" --settings @menu-sheet.json
screenrig source create --kind json --card crd_01EXAMPLEKPI00000000000 --name "Daily numbers" --settings @kpi-api.json --secret token=@api.token
screenrig source create --kind square --card crd_01EXAMPLEMENU0000000000 --name "Counter menu" --secret access_token=@square.token
screenrig source create --kind microsoft365 --card crd_01EXAMPLEROOMS0000000000 --name "Meeting rooms" --settings @rooms.json --connection-id pcn_01EXAMPLECONNECTION0000
screenrig source create --preset slack-channel --card crd_01EXAMPLEWALL00000000000 --name "Team wall" --set channel=C0123456789 --secret token=@slack.token
```

### `source update`

Change a source. A change other than a rename resets its failure count and runs it again.

```console
source update <source_id> [--name NAME] [--card CARD_ID] [--settings JSON|@FILE|-] [--set KEY=VALUE]...
                          [--connection-id ID] [--secret NAME=VALUE]... [--unset-secret NAME]... [--refresh DURATION]
                          [--stale-after DURATION|none] [--enable | --disable] [--expect-rev REVISION]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<source_id>` | string | yes | none | The source (`src_…`). |
| `--name NAME` | string | no | unchanged | Rename the source. |
| `--card CARD_ID` | string | no | unchanged | Write another card. |
| `--settings SETTINGS` | string | no | unchanged | Replace the whole settings object: JSON, `@FILE` or `-` for stdin. For a source made from a preset, merge these fields into its settings. |
| `--connection-id ID` | string | no | unchanged | As for `source create`. Moving a source off its own credentials takes `--settings` without `tenant` and `client_id`, and `--unset-secret client_secret`. |
| `--set KEY=VALUE` | string | no | none | Change one top-level setting of the saved ones, as for `source create`. Repeatable. For a source made from a preset, one field of the preset; the value `null` removes an optional field. |
| `--secret NAME=VALUE` | string | no | none | Set or replace a secret. Repeatable. A secret you do not send keeps its value unless the change points the source somewhere that secret does not cover (another origin, store, environment or tenant): then `source_secret_required` asks for it again. |
| `--unset-secret NAME` | string | no | none | Remove a secret. Repeatable. |
| `--refresh DURATION` | string | no | unchanged | `30s` to `24h`; the kind's shortest applies. |
| `--stale-after DURATION` | string | no | unchanged | As for `source create`; `none` removes the period. |
| `--enable`, `--disable` | boolean | no | unchanged | Resume the schedule, or stop it; the card keeps its last document. At most one. |
| `--expect-rev REVISION` | integer | no | the revision read | Refuse the change unless the source is at this revision. `--set` guards the revision it read unless you name another. |

At least one change is required.

```console
screenrig source update src_01EXAMPLESOURCE000000 --set days=14
screenrig source update src_01EXAMPLESOURCE000000 --secret calendar_url.lobby=@new.url --refresh 10m
screenrig source update src_01EXAMPLESOURCE000000 --disable
screenrig source update src_01EXAMPLEPRESET0000000 --set channel=C0123456789 --secret token=@new.token
```

### `source test`

Preview a source without saving or writing anything: fetch the address, shape the answer for the card and check it against the card. The envelope carries the document, `valid`, the path and reason when the card refuses it, warnings and counts. Pass a saved `<source_id>` to test it with the other options as overrides, or `--kind` (or `--preset`) and `--card` to test one that is not saved. A fetch or shaping failure is `source_test_failed` with the reason. A `csv` or `json` source also reports the request that went out as `data.request`: its address with placeholders filled in and secret query parameters masked, the names of the headers sent, the start of the body and the pages read. At most 30 previews a minute per organization.

```console
source test [<source_id>] [--kind KIND | --preset NAME] [--card CARD_ID] [--settings JSON|@FILE|-] [--set KEY=VALUE]...
            [--connection-id ID] [--secret NAME=VALUE]...
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<source_id>` | string | no | none | A saved source to test. |
| `--kind KIND` | string | without `<source_id>` or `--preset` | none | As for `source create`. |
| `--preset NAME` | string | no | none | Preview a source made from this preset, with `--set` and `--settings` as its fields and `--secret` as its credentials, instead of `--kind`. Not with `<source_id>`. |
| `--card CARD_ID` | string | without `<source_id>` | none | The card to fill. |
| `--settings SETTINGS` | string | no | the saved settings | The kind's settings: JSON, `@FILE` or `-` for stdin. |
| `--connection-id ID` | string | no | none | As for `source create`. |
| `--set KEY=VALUE` | string | no | none | One top-level setting, as for `source create`; with a `<source_id>` it overrides that setting of the saved ones. Repeatable. |
| `--secret NAME=VALUE` | string | no | the saved secrets | A credential to try. Repeatable. |

```console
screenrig source test --kind ics --card crd_01EXAMPLECARD000000000 --set calendars='[{"key":"lobby"}]' --secret calendar_url.lobby=@lobby.url
screenrig source test src_01EXAMPLESOURCE000000
screenrig source test --preset slack-channel --card crd_01EXAMPLEWALL00000000000 --set channel=C0123456789 --secret token=@slack.token
```

### `source refresh`

Sync a source now and show the result. It runs inline for up to 60 seconds, resets the failure count and reads the address in full. A failed sync never changes the card. `source_busy` (exit 5) answers while a scheduled sync is running. At most 6 a minute per source.

```console
source refresh <source_id>
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<source_id>` | string | yes | none | The source (`src_…`). |

```console
screenrig source refresh src_01EXAMPLESOURCE000000
```

### `source rooms`

Check how screens map to the rooms of a booking-system source (`momentus`). It reads the rooms of the source's last good refresh and the project's screens, and fetches nothing. It lists the rooms and areas no screen shows and every screen that has a room or area value or whose playlist reads the source's room or area key, each `mapped`, `missing` (the playlist reads the field and the screen has none) or `unknown` (the value names no room or area, with the one it probably meant). Fix a screen with `screen update scr_ID --field room=ROOM_KEY`.

```console
source rooms <source_id>
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<source_id>` | string | yes | none | A source (`src_…`) that reads a booking system's rooms. |

```console
screenrig source rooms src_01EXAMPLESOURCE000000
```

### `source delete`

Delete a source. The card keeps the last document the source wrote.

```console
source delete <source_id> [--expect-rev REVISION]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<source_id>` | string | yes | none | The source (`src_…`). |
| `--expect-rev REVISION` | integer | no | none | Refuse the delete unless the source is at this revision. |

```console
screenrig source delete src_01EXAMPLESOURCE000000
```

## Connections

A connection is the project's saved access to Microsoft or Google for work that runs with nobody signed in. A `microsoft365` or `google_calendar` data source (`source create --connection-id`), a Power BI connection (`bi connection create powerbi --connection-id`) and a SharePoint media sync account (`media sync account add microsoft365 --connection-id`) read through one instead of each carrying a tenant, a client ID and a secret. A connection ID starts `pcn_`, and an organization has up to 50 connections across its projects. The modes, statuses and approval steps are on [Connect Microsoft and Google](https://screenrig.ai/docs/connections.md).

Mode `own_app` holds your own application: for Microsoft a Microsoft Entra app registration (`--tenant-id`, `--client-id` and the Value of a client secret), for Google a service account's JSON key. Mode `screenrig_app` uses screenRIG's own application and needs no secret: `create` prints a one-time consent link (`data.consent_url`, expiring at `data.consent_expires_at`) for the person who completes it, a Microsoft 365 administrator who consents for the tenant, or the holder of a Google account who grants read-only calendar access. Send the link to that person only, then read `status` and `last_error` with `connection show`. A Power BI connection takes only an `own_app` connection.

Give a client secret with `--secret-file FILE` and a Google key with `--service-account-key-file FILE`, or `-` for stdin, never as an argument. Reading needs Read access, and every change needs Manage access.

### `connection list`

List this project's connections with their status.

```console
connection list
```

No parameters.

```console
screenrig connection list
```

### `connection show`

Inspect one connection: its status, last error and last test.

```console
connection show <id>
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<id>` | string | yes | none | The connection (`pcn_…`). |

```console
screenrig connection show pcn_01EXAMPLECONNECTION0000
```

### `connection create microsoft`

Add a Microsoft 365 connection: your own Entra app, or screenRIG's application with a consent link.

```console
connection create microsoft --mode own_app|screenrig_app [--name NAME]
    [--tenant-id ID --client-id ID --secret-file FILE]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `--mode MODE` | string | yes | none | `own_app`: your own Microsoft Entra app registration with a client secret. `screenrig_app`: screenRIG's application, which a Microsoft 365 administrator consents to through the one-time link this command prints. |
| `--name NAME` | string | no | `Microsoft 365` | 1 to 80 characters. |
| `--tenant-id ID` | string | with `own_app` | none | Your Microsoft Entra Directory (tenant) ID, or its primary domain such as `contoso.onmicrosoft.com`. Together with `--client-id` and `--secret-file`. |
| `--client-id ID` | string | with `own_app` | none | The Application (client) ID of the app registration. |
| `--secret-file FILE` | string | with `own_app` | none | Read the client secret's Value from this file, or `-` for stdin (never an argument); the file holds only the Value. |

```console
screenrig connection create microsoft --mode own_app --tenant-id contoso.onmicrosoft.com --client-id 0b1d2f3a-4c5e-4f60-8a7b-9c0d1e2f3a4b --secret-file secret.txt
screenrig connection create microsoft --mode screenrig_app --name "Contoso rooms"
```

Mode `screenrig_app` takes none of `--tenant-id`, `--client-id` and `--secret-file`: it prints the consent link (`data.consent_url`) for the Microsoft 365 administrator, who consents to screenRIG's application for the tenant. The app registration lists `Calendars.Read` for meeting-room calendars, `Sites.Selected` or `Files.Read.All` for SharePoint media sync and, for Power BI, tenant settings and workspace membership instead of Graph permissions; `connection test` reports which permissions the token carries. A server without screenRIG's application answers `connection_app_not_configured`: mode `own_app` still works.

### `connection create google`

Add a Google connection: your own service account key, or screenRIG's application with a sign-in link.

```console
connection create google --mode own_app|screenrig_app [--name NAME]
    [--service-account-key-file FILE]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `--mode MODE` | string | yes | none | `own_app`: your own service account key. `screenrig_app`: screenRIG's application, which the holder of a Google account signs in to and grants read-only calendar access through the one-time link this command prints. |
| `--name NAME` | string | no | `Google Calendar` | 1 to 80 characters. |
| `--service-account-key-file FILE` | string | with `own_app` | none | Read the service account's JSON key file from this file, or `-` for stdin (never an argument). |

```console
screenrig connection create google --mode own_app --service-account-key-file key.json
screenrig connection create google --mode screenrig_app --name "Venue calendars"
```

In mode `own_app`, share each room calendar with the service account's address, or give the source a subject (domain-wide delegation). Mode `screenrig_app` takes no key and prints the sign-in link (`data.consent_url`) for the holder of the Google account: the account must see every room calendar a source lists, and such a source cannot name a subject. A server without screenRIG's application answers `connection_app_not_configured`: mode `own_app` still works.

### `connection update`

Rename a connection or, in mode `own_app`, change its tenant, app or secret.

```console
connection update <id> [--name NAME] [--tenant-id ID] [--client-id ID]
    [--secret-file FILE] [--service-account-key-file FILE] [--expect-rev REVISION]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<id>` | string | yes | none | The connection (`pcn_…`). |
| `--name NAME` | string | no | unchanged | Rename the connection. |
| `--tenant-id ID` | string | no | unchanged | Microsoft `own_app`: the Directory (tenant) ID or primary domain. |
| `--client-id ID` | string | no | unchanged | Microsoft `own_app`: the Application (client) ID. |
| `--secret-file FILE` | string | no | unchanged | Microsoft `own_app`: read the client secret's Value from this file, or `-` for stdin; it replaces the stored secret. |
| `--service-account-key-file FILE` | string | no | unchanged | Google `own_app`: read the service account's JSON key from this file, or `-` for stdin; it replaces the stored key. |
| `--expect-rev REVISION` | integer | no | none | Refuse the change unless the connection is at this revision (`revision_conflict`, exit 6). |

```console
screenrig connection update pcn_01EXAMPLECONNECTION0000 --secret-file new-secret.txt
screenrig connection update pcn_01EXAMPLECONNECTION0000 --name "Contoso rooms" --expect-rev 2
```

At least one change is required. A change to the credentials returns the connection to `ready`, clears its last error and last test, and retires every token minted for the old ones: test it again. A `screenrig_app` connection can only be renamed: `connection connect` makes a new consent link to change who consented. An omitted secret is kept.

### `connection test`

Sign in with a connection and check what its credentials allow.

```console
connection test <id>
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<id>` | string | yes | none | The connection (`pcn_…`). |

```console
screenrig connection test pcn_01EXAMPLECONNECTION0000
```

For Microsoft it reports `credentials` (an app token for the tenant) and `permissions` (which of `Calendars.Read`, `Sites.Selected`, `Files.Read.All`, `Sites.Read.All` and `Place.Read.All` the token carries; none fails, and `Sites.Selected` alone is a warning because each site needs its own grant). For Google it reports `credentials`, naming the account the calendars must be visible to. A refusal moves the connection to `error` with `last_error`; a success returns it to `ready`. The test does not judge a calendar's sharing, a mailbox access policy or a site grant. At most 30 a minute per organization.

### `connection connect`

Make a new one-time consent link for a `screenrig_app` connection.

```console
connection connect <id>
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<id>` | string | yes | none | The connection (`pcn_…`). |

```console
screenrig connection connect pcn_01EXAMPLECONNECTION0000
```

`data.consent_url` is the link for the person who completes the consent: the Microsoft 365 administrator, or the holder of the Google account. It replaces any earlier link. A connection that works stays as it is until the new consent completes, so this also renews one that moved to `error` (consent removed, access revoked) or moves it to another tenant or account. A connection in mode `own_app` has no consent step. At most 20 a minute per organization.

### `connection delete`

Delete a connection that nothing reads through.

```console
connection delete <id> [--expect-rev REVISION]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `<id>` | string | yes | none | The connection (`pcn_…`). |
| `--expect-rev REVISION` | integer | no | none | Refuse the delete unless the connection is at this revision (`revision_conflict`, exit 6). |

```console
screenrig connection delete pcn_01EXAMPLECONNECTION0000
screenrig connection delete pcn_01EXAMPLECONNECTION0000 --expect-rev 2
```

While a data source, a Power BI connection or a media sync account reads through the connection the answer is `resource_conflict` (exit 5), naming them. Deleting does not end the vendor's side: a Microsoft 365 tenant keeps screenRIG's application until its administrator removes it, and a Google account keeps its grant until its holder revokes it.

## Other command groups

- [Projects](https://screenrig.ai/docs/cli/projects.md)
- [Service clients](https://screenrig.ai/docs/cli/service-clients.md)
- [Help and support](https://screenrig.ai/docs/cli/help.md)
- [Media](https://screenrig.ai/docs/cli/media.md)
- [Media sync](https://screenrig.ai/docs/cli/media-sync.md)
- [Playlists](https://screenrig.ai/docs/cli/playlists.md)
- [Cards](https://screenrig.ai/docs/cli/cards.md)
- [Applications](https://screenrig.ai/docs/cli/applications.md)
- [Screens](https://screenrig.ai/docs/cli/screens.md)
- [Schedules](https://screenrig.ai/docs/cli/schedules.md)
- [Campaigns](https://screenrig.ai/docs/cli/campaigns.md)
- [Device health](https://screenrig.ai/docs/cli/device.md)
- [Reviews and notes](https://screenrig.ai/docs/cli/reviews.md)
- [Notifications](https://screenrig.ai/docs/cli/notifications.md)
- [Reports](https://screenrig.ai/docs/cli/reports.md)
- [BI dashboards](https://screenrig.ai/docs/cli/bi.md)
- [Triggers](https://screenrig.ai/docs/cli/triggers.md)
- [Fleet links](https://screenrig.ai/docs/cli/fleet-links.md)
- [Advertising](https://screenrig.ai/docs/cli/ads.md)