# Service clients CLI commands

> Canonical HTML: https://screenrig.ai/docs/cli/service-clients

Create service clients, add and remove their keys and secrets, and revoke them: the sign-in for servers, scripts and CI jobs. 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.

## Service clients

A service client is a server, script or CI job owned by the project, signing in with its own key or secret instead of a person's approval. To create or change a client, the agent needs Manage identity access with the `identity` scope, its own Manage grant with the `project` capability on the target project, and a verified responsible person who administers that project's organization. A service client never manages clients. To run commands as the client, run `screenrig --config PATH login --client-id scl_ID --client-key-file KEY.pem` (or `--client-secret-file FILE`) once and use that configuration; `screenrig logout` removes the saved client. See [Service clients](https://screenrig.ai/docs/service-clients.md).

### `service-client list`

List this project's service clients, live and revoked, with their keys, secret ids and usage.

```console
service-client list
```

No parameters.

```console
screenrig service-client list
```

Never returns a secret.

### `service-client show`

Show one service client.

```console
service-client show ID
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `ID` | string | yes | none | The client id, `scl_…`. |

```console
screenrig service-client show scl_ID
```

Lists each key's `kid` and each secret's `css_` id for rotation.

### `service-client create`

Create a service client owned by this project.

```console
service-client create --name NAME [--capability NAME]... [--access read|propose|manage]
                      [--uploader --folder-id IDS [--playlist-id IDS]] [--key-file PATH] [--secret-file PATH]
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `--name NAME` | string | yes | none | 1 to 80 characters. |
| `--capability NAME` | string | no | all six | Repeatable: `screens`, `content`, `playlists`, `advertising`, `reports`, `project`, each within yours. |
| `--access LEVEL` | string | no | read | `read`, `propose` or `manage`; `propose` for an uploader. `propose` sends playlist and screen changes to a person's [review](https://screenrig.ai/docs/cli/reviews.md#reviews). |
| `--uploader` | boolean | no | off | Limit the client to the media folders and playlists given with `--folder-id` and `--playlist-id`. |
| `--folder-id IDS` | string | with `--uploader` | none | Comma-separated `mfd_` media folders the client uploads into; at least one. |
| `--playlist-id IDS` | string | no | none | With `--uploader`: comma-separated `pl_` playlists whose pages the client changes. |
| `--key-file PATH` | path | one of these | none | A JWK or PEM: Ed25519, EC P-256 or RSA of at least 2048 bits. Only the public half is sent. |
| `--secret-file PATH` | path | one of these | none | Generate a secret and write it to this new 0600 file. It is shown once. |

```console
screenrig service-client create --name "Nightly report" --access read --capability reports --key-file screenrig-client.pem
screenrig service-client create --name "Agency agent" --uploader --folder-id mfd_01EXAMPLEFOLDER000000000 --playlist-id pl_01EXAMPLEPLAYLIST000000 --secret-file agency.secret
```

Needs the identity, project and organization admin authority described above. An uploader works only in its folders and playlists: it uploads media into them and adds, replaces and removes pages of those playlists, and anything else is `outside_upload_scope`. At most 50 live clients per organization, counted across its projects. A key without its own `kid` is known by its RFC 7638 thumbprint.

### `service-client add-key`

Register a second public key for a rotation without downtime.

```console
service-client add-key ID --key-file PATH
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `ID` | string | yes | none | The client id. |
| `--key-file PATH` | path | yes | none | The new public key, a JWK or PEM. |

```console
screenrig service-client add-key scl_ID --key-file new.pem
```

A client holds at most two keys.

### `service-client add-secret`

Generate a second secret for a rotation without downtime.

```console
service-client add-secret ID --secret-file PATH
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `ID` | string | yes | none | The client id. |
| `--secret-file PATH` | path | yes | none | A new 0600 file that receives the secret. |

```console
screenrig service-client add-secret scl_ID --secret-file new-secret
```

A client holds at most two secrets. The current one keeps working until you remove it.

### `service-client remove-key`

Remove a key; tokens issued with it stop working within seconds.

```console
service-client remove-key ID --kid KID
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `ID` | string | yes | none | The client id. |
| `--kid KID` | string | yes | none | The key id from `service-client show`. |

```console
screenrig service-client remove-key scl_ID --kid KID
```

A client keeps at least one key or secret.

### `service-client remove-secret`

Remove a secret; tokens issued with it stop working within seconds.

```console
service-client remove-secret ID --secret-id css_ID
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `ID` | string | yes | none | The client id. |
| `--secret-id ID` | string | yes | none | The `css_` secret id from `service-client show`. |

```console
screenrig service-client remove-secret scl_ID --secret-id css_ID
```

A client keeps at least one key or secret.

### `service-client revoke`

Revoke a service client permanently.

```console
service-client revoke ID --yes
```

| Parameter | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `ID` | string | yes | none | The client id. |
| `--yes` | boolean | yes | off | Confirm the permanent revocation. |

```console
screenrig service-client revoke scl_ID --yes
```

Deletes its keys and secrets; its tokens stop working within seconds. The record stays for audit.

## Other command groups

- [Projects](https://screenrig.ai/docs/cli/projects.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)
- [Data sources](https://screenrig.ai/docs/cli/data-sources.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)