Media sync CLI commands

Add your own Microsoft Entra app, or a Microsoft connection of the project, so a sync can read a SharePoint or OneDrive for work folder.

media sync account add microsoft365 --name NAME
    (--tenant-id TENANT --client-id ID --secret-file FILE | --connection-id ID)

screenrig media sync account add microsoft365 --name Contoso --tenant-id contoso.onmicrosoft.com --client-id 0b1d2f3a-4c5e-4f60-8a7b-9c0d1e2f3a4b --secret-file secret.txt
screenrig media sync account add microsoft365 --name Contoso --connection-id pcn_01EXAMPLECONNECTION0000

In the Microsoft Entra admin center, register a single-tenant app with no redirect URI, add a client secret (copy its Value, not its Secret ID), add the Microsoft Graph application permission Sites.Selected (then grant the app read access to each site) or Files.Read.All, and grant admin consent. The app belongs to this project. Run media sync account test next.

Add a Dropbox account and print the one-time link its owner opens, signed in to Dropbox, to connect it.

media sync account add dropbox --name NAME [--app-key KEY]

screenrig media sync account add dropbox --name "Marketing Dropbox"
screenrig media sync account add dropbox --name "Marketing Dropbox" --app-key YOURAPPKEY

data.authorize_url is the link and data.authorize_expires_at its expiry. The CLI never opens a browser: send the link to the person who owns the Dropbox account, who allows read-only access (files.metadata.read, files.content.read, account_info.read, sharing.read). Run media sync account show until data.state is ready (it starts as pending_consent), then media sync create dropbox. Your own Dropbox app needs those permissions enabled and the redirect URI that the output prints.

Add a Google Drive account, ready at once, and print the service account address that folders are shared with.

media sync account add google-drive --name NAME [--key-file FILE]

screenrig media sync account add google-drive --name "Marketing Drive"
screenrig media sync account add google-drive --name "Marketing Drive" --key-file key.json

data.config.service_account_email is the address to share each folder with; Viewer is enough. Through screenRIG's service account a folder syncs only when a member of this project with a verified email shared it or owns it (media_sync_sharer_not_member otherwise). With your own key, any folder shared with the service account syncs.

List this project's media sync accounts with their kind, state and last test; no secret is returned.

media sync account list

No parameters.

screenrig media sync account list

Inspect one account: its tenant and client ID, state, masked secret and last test.

media sync account show <id>

screenrig media sync account show msa_01EXAMPLEACCOUNT0000000

A Dropbox account also shows who connected it and its app_key; a Google Drive account shows its service_account_email.

Rename an account, change a Microsoft app's tenant, application ID or client secret, or replace a Google Drive account's own key.

media sync account update <id> [--name NAME] [--tenant-id TENANT] [--client-id ID]
    [--secret-file FILE | --key-file FILE] [--expect-rev REVISION]

screenrig media sync account update msa_01EXAMPLEACCOUNT0000000 --secret-file new-secret.txt
screenrig media sync account update msa_01EXAMPLEACCOUNT0000000 --name "Contoso tenant" --expect-rev 2

At least one change is required. A change of credentials clears last_test: test the account again. Entra client secrets expire, so replace the secret here before it does.

Make a new one-time link to connect, or reconnect, a Dropbox account.

media sync account connect <id>

screenrig media sync account connect msa_01EXAMPLEACCOUNT0000000

data.authorize_url and data.authorize_expires_at carry the link, which replaces the earlier one. Send it to the person who owns the Dropbox account. Use it when the person did not finish or the account is reconnect_required (Dropbox no longer honors the connection). A connected account stays connected until the new consent completes, and another Dropbox account signing in takes over the connection.

Check an account: a Microsoft app's sign-in and Graph permissions, or the connection or key of a Dropbox or Google Drive account.

media sync account test <id>

screenrig media sync account test msa_01EXAMPLEACCOUNT0000000

The answer is stored as last_test. For a Microsoft app it reports credentials (Microsoft issued a token; a refusal carries its AADSTS code, such as AADSTS7000215 for a secret that is the ID rather than the Value) and permissions (the Graph application permissions the token carries). Sites.Selected alone is a warning: each site still needs its grant, and a sharing link needs Files.Read.All. The test does not judge a site's grant or a folder: media sync create reads the folder you name. A failed check is data.ok false with exit 0.

Delete an account no sync uses.

media sync account delete <id> [--expect-rev REVISION]

screenrig media sync account delete msa_01EXAMPLEACCOUNT0000000

While syncs use the account the answer is resource_conflict (exit 5), naming them: delete those first.

Sync a SharePoint or OneDrive for work folder into a media folder.

media sync create sharepoint --account-id ID --url URL [--folder-id ID] [--every DURATION] [--name NAME]

screenrig media sync create sharepoint --account-id msa_01EXAMPLEACCOUNT0000000 --url https://contoso.sharepoint.com/sites/Marketing/Shared%20Documents/Lobby%20Signs
screenrig media sync create sharepoint --account-id msa_01EXAMPLEACCOUNT0000000 --url "https://contoso.sharepoint.com/:f:/s/Marketing/EabcDEF" --folder-id mfd_01EXAMPLEFOLDER000000000 --every 1h --name "Lobby signs"

A folder Microsoft refuses is media_sync_source_refused (exit 5), with the permission to grant; nothing is stored.

Sync a Dropbox folder into a media folder.

media sync create dropbox --account-id ID --url URL|PATH [--folder-id ID] [--every DURATION] [--name NAME]

screenrig media sync create dropbox --account-id msa_01EXAMPLEACCOUNT0000000 --url https://www.dropbox.com/home/Marketing/Lobby%20Signs
screenrig media sync create dropbox --account-id msa_01EXAMPLEACCOUNT0000000 --url /Marketing/Lobby --folder-id mfd_01EXAMPLEFOLDER000000000 --every 1h --name "Lobby signs"

Each run continues from Dropbox's saved position in the folder and reads only what changed. A folder the account cannot open is media_sync_source_refused, and a connection Dropbox no longer honors is dropbox_reconnect_required (media sync account connect): both exit 5, nothing stored.

Sync a Google Drive folder shared with an account's service account into a media folder.

media sync create google-drive --account-id ID --url URL|ID [--folder-id ID] [--every DURATION] [--name NAME]

screenrig media sync create google-drive --account-id msa_01EXAMPLEACCOUNT0000000 --url https://drive.google.com/drive/folders/1AbCdEfGhIjKlMnOpQrStUvWxYz --folder-id mfd_01EXAMPLEFOLDER000000000 --every 1h
screenrig media sync create google-drive --account-id msa_01EXAMPLEACCOUNT0000000 --url 1AbCdEfGhIjKlMnOpQrStUvWxYz

Through screenRIG's service account the folder syncs only when a member of this project with a verified email shared it or owns it (media_sync_sharer_not_member, exit 3, nothing stored). Every run checks that again, and a folder that loses such a sharer stops the sync in state error with its media kept: share it again from a member's Google account, then run media sync update ID --resume. Google Docs, Sheets and Slides files are skipped as unsupported_type. A folder the address cannot open is media_sync_source_refused (exit 5): share it with the service account.

List this project's media syncs with their media folder, cadence, state and last run status.

media sync list

No parameters.

screenrig media sync list

Inspect one sync and the summary of its last run.

media sync show <id>

screenrig media sync show msy_01EXAMPLESYNC000000000

data.last_run carries status (ok, partial or error), added, updated, removed, pending_delete (removed files a screen still holds, waiting in the Removed folder), skipped_total and skipped, the first 20 skipped files with each file's reason (unsupported_type, too_large, storage, subfolder, download_failed, unreadable, in_use); a failed run carries error with a code and a detail that name the fix. data.source adds path for Dropbox and shared_by for Google Drive.

A sync in state error needs a repair. Its media folder was deleted: point it at another with media sync update --folder-id. Its source folder was deleted or moved: delete the sync and create one. For Google Drive through screenRIG's service account, the folder lost its verified sharer (sharer_not_member): share it again from a project member's Google account, then media sync update ID --resume. A Dropbox run fails with reconnect_required when Dropbox stops honoring the connection (media sync account connect).

Change a sync's name, cadence or media folder, or pause and resume it.

media sync update <id> [--name NAME] [--every DURATION] [--folder-id ID]
    [--pause | --resume] [--expect-rev REVISION]

screenrig media sync update msy_01EXAMPLESYNC000000000 --every 1h
screenrig media sync update msy_01EXAMPLESYNC000000000 --pause
screenrig media sync update msy_01EXAMPLESYNC000000000 --folder-id mfd_01EXAMPLEFOLDER000000000 --expect-rev 3

At least one change is required.

Run a sync now instead of at its next time.

media sync run <id>

screenrig media sync run msy_01EXAMPLESYNC000000000

The sync runs within about 30 seconds, and media sync show then shows its last run. A paused sync must be resumed first.

Stop a sync; its media and folder stay.

media sync delete <id> [--expect-rev REVISION]

screenrig media sync delete msy_01EXAMPLESYNC000000000

The sync forgets which source file became which media. The imported media and the media folder stay, and nothing is removed.