BI connections
A BI connection is the project's access to a system it owns that shows dashboards: for Grafana its address and a service-account token, for Power BI a Microsoft Entra app (service principal) and its client secret, for Tableau a connected app and a user, and for a web page the service account of a site that shows a dashboard behind a sign-in, or the cookies of a signed-in browser. A connection ID starts bic_. Secrets are sealed on the server and never shown again: a read shows secret {set, hint}, where hint is the last four characters of a secret of 12 or more. Connections belong to one project. bi connection list, show and browse need Read access, and every other command needs Manage access. A plan without BI dashboards answers feature_not_in_plan (exit 8) to creating a connection or a view and to changing one, except replacing a credential; pricing lists the plans.
Give a secret in a file: --token-file for Grafana, --secret-file for Power BI and Tableau, --password-file, --totp-file and --cookies-file for a web page. Each takes - for stdin, never an argument, and so does a web connection's --steps script; at most one option of a command reads stdin.
A view plays one dashboard, report or page of a connection through an iframe primitive that shows its embed_url; bi view create --connection-id ID makes one. Show a dashboard behind a sign-in walks through a web connection, and the API reference covers every kind.
bi connection create grafana#
Add a Grafana connection: its address and a service-account token.
bi connection create grafana --url URL --token-file FILE [--name NAME] [--org-id N]| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
--url URL | string | yes | none | Grafana's address on a public host, with any path prefix: https://grafana.example.com or https://example.com/grafana. A private, loopback or reserved address is invalid_request (exit 8), and Grafana must answer without redirecting. |
--token-file FILE | string | yes | none | Read the service-account token from this file, or - for stdin (never an argument); the file holds only the token. |
--name NAME | string | no | the host name | 1 to 80 characters. |
--org-id N | integer | no | 1 | The Grafana organization the token belongs to: a whole number from 1. |
screenrig bi connection create grafana --url https://grafana.example.com --token-file token.txt
screenrig bi connection create grafana --url https://example.com/grafana --token-file - --name "Ops Grafana" --org-id 2In Grafana, install the Grafana Image Renderer plugin or the remote rendering service (it draws dashboards as images; without it nothing renders), then create a service account with the Viewer role and add a token. Run bi connection test next.
bi connection create tableau#
Add a Tableau connection: a connected app (direct trust), the user the screens' views are shown as, and the app's secret value.
bi connection create tableau --url URL --client-id ID --secret-id ID --username USER
--secret-file FILE [--site SITE] [--name NAME]| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
--url URL | string | yes | none | The https address of Tableau Server, or of your Tableau Cloud pod such as https://10ay.online.tableau.com (the pod, not online.tableau.com). |
--site SITE | string | no | Tableau Server's default site | The site's content URL, the part after /site/ or /t/ in a view's address. |
--client-id ID | string | yes | none | The connected app's Client ID. |
--secret-id ID | string | yes | none | The Secret ID of a secret generated for the connected app. |
--username USER | string | yes | none | The Tableau user the screens' views are shown as (an email address on Tableau Cloud). |
--secret-file FILE | string | yes | none | Read the secret's value from this file, or - for stdin (never an argument); the file holds only the secret value, not the Secret ID. |
--name NAME | string | no | the host name | 1 to 80 characters. |
screenrig bi connection create tableau --url https://10ay.online.tableau.com --site lobby --client-id 11111111-2222-3333-4444-555555555555 --secret-id 66666666-7777-8888-9999-000000000000 --username screens@example.com --secret-file secret.txtSet up once in Tableau: under Settings, Connected Apps, create a Direct trust connected app, copy its Client ID, generate a secret and copy the Secret ID and the secret value, and enable the app and the secret. Pick or create the Tableau user the screens show and give it access to only the views screens show: anyone who holds a screen's ticket can embed any view that user can see. Then run bi connection show ID and enter the host of its embed_origin in the connected app's domain allowlist. It needs Tableau Cloud or Tableau Server 2023.3 or later; the screens must reach the Tableau host, and their browser must accept third-party cookies from it. Run bi connection test next, then bi connection browse to find a view.
bi connection create powerbi#
Add a Power BI connection: a Microsoft Entra app (service principal) and its client secret, or a Microsoft connection of this project.
bi connection create powerbi
(--tenant-id ID --client-id ID --secret-file FILE | --connection-id ID) [--name NAME]| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
--tenant-id ID | string | without --connection-id | none | Your Microsoft Entra Directory (tenant) ID, or its domain such as contoso.onmicrosoft.com; not common, organizations or consumers. Together with --client-id and --secret-file. |
--client-id ID | string | without --connection-id | none | The Application (client) ID of the app registration. |
--secret-file FILE | string | without --connection-id | none | Read the client secret's Value from this file, or - for stdin (never an argument); the file holds only the secret value, not the secret ID. |
--connection-id ID | string | without --tenant-id | none | Sign in through a Microsoft connection (pcn_…) of this project in mode own_app, instead of --tenant-id, --client-id and --secret-file. A screenrig_app connection is refused. Not with them. |
--name NAME | string | no | Power BI | 1 to 80 characters. |
screenrig bi connection create powerbi --tenant-id 11111111-2222-3333-4444-555555555555 --client-id aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --secret-file secret.txt
screenrig bi connection create powerbi --connection-id pcn_01EXAMPLECONNECTION0000 --name "Contoso Power BI"Set up once. In Microsoft Entra, create an app registration (single tenant, no redirect URI, no API permissions) and a client secret. A Power BI admin turns on, in the admin portal under Tenant settings, Developer settings, Embed content in apps and Service principals can call Fabric public APIs, for the whole organization or for a security group that holds the app. Add the app to each workspace you show with the Member or Admin role; Member is the least access. For production embedding the workspace must sit on a Fabric (F), Power BI Embedded (A) or Premium (P/EM) capacity. Commercial cloud only. Run bi connection test next, then bi connection browse to find a workspace and a report.
bi connection create web#
Add a web connection: a service account of a site that shows a dashboard behind a sign-in, or the cookies of a signed-in browser.
bi connection create web --login-mode auto|steps|none [--login-url URL] [--username USER]
[--password-file FILE] [--totp-file FILE] [--steps FILE] [--cookies-file FILE] [--name NAME]| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
--login-mode MODE | string | yes | none | auto fills the form on --login-url with --username and the password. steps runs the --steps script. none signs nothing in, so pages show with the --cookies-file jar and takes none of --login-url, --username, --password-file, --totp-file or --steps. |
--login-url URL | string | with auto or steps | none | The https address of the site's sign-in page, on a public host. The password is typed only there and in the script's goto steps, never into a view's address. |
--username USER | string | with auto | none | The service account's username, which a steps script reads as {{username}}. |
--password-file FILE | string | with auto | none | Read the service account's password from this file, or - for stdin (never an argument): spaces are allowed, and trailing line endings are dropped. |
--totp-file FILE | string | no | none | Read the base32 key the site shows for the account's authenticator app (16 to 128 characters), or its otpauth://totp address, from this file or -: the server computes the codes. |
--steps FILE | string | with steps | none | The sign-in script, a JSON array of at most 30 steps, from a file or -. Actions: goto (url), fill (selector, value), click and wait_for (selector), press (value such as Enter, optional selector) and wait_ms (ms, 1 to 10000). A value may hold {{username}}, {{password}} and {{otp}}, never the secret itself. Not with auto. |
--cookies-file FILE | string | no | none | A cookie jar exported from a signed-in browser: a JSON array of cookies (a cookie extension's export) or an object with a cookies array (Playwright's storage state), from a file or -; at most 100. Only name, value, domain, path, expires, httpOnly, secure and sameSite are sent. |
--name NAME | string | no | the sign-in host, or Web page with --login-mode none | 1 to 80 characters. |
screenrig bi connection create web --login-mode auto --login-url https://login.example.com/signin --username screens@example.com --password-file password.txt --name "Ops dashboard"
screenrig bi connection create web --login-mode steps --login-url https://login.example.com/signin --username screens@example.com --password-file password.txt --steps steps.json
screenrig bi connection create web --login-mode none --cookies-file cookies.json --name "Signed-in jar"The password, the key and the cookies are sealed and never shown again: data.secret and data.totp_secret say whether they are set, and data.session says where the sign-in stands (idle, active, login_needed, paused, stopped or expired). Use a read-only service account. A refused sign-in waits 5 minutes, then 15, 60 and 120, and the fifth in a row stops the connection until its credentials or sign-in settings change. A site that approves sign-ins on a phone, checks devices or shows a CAPTCHA cannot be scripted: use a cookie jar. A server without the page renderer answers bi_web_unavailable (exit 5). Run bi connection test next.
bi connection list#
List this project's BI connections with their kind, masked secret and last test.
bi connection listNo parameters.
screenrig bi connection listdata.items holds every connection of the project; no secret is returned.
bi connection show#
Inspect one connection and its last test.
bi connection show <id>| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
<id> | string | yes | none | The connection (bic_…). |
screenrig bi connection show bic_01EXAMPLECONNECTION0000The answer carries kind, config (url and org_id for Grafana; tenant_id and client_id for Power BI, or connection_id when a Microsoft connection signs in; url, site, client_id, secret_id and username for Tableau; login_mode, login_url, username and steps for a web connection), secret {set, hint}, embed_origin (the project's embed host, which a connected app's domain allowlist names) and last_test. A web connection also carries totp_secret {set} and session: its state, the cookies count and cookies_updated_at, last_login_at, login_failures and retry_at.
bi connection update#
Change a connection's name, address, organization, tenant, app, site, user, secret or, for a web connection, its sign-in and cookies.
bi connection update <id> [--name NAME] [--url URL] [--org-id N] [--tenant-id ID] [--client-id ID]
[--site SITE | --default-site] [--secret-id ID] [--username USER]
[--token-file FILE | --secret-file FILE | --password-file FILE | --clear-password]
[--login-mode auto|steps|none] [--login-url URL] [--totp-file FILE | --clear-totp]
[--steps FILE] [--cookies-file FILE | --clear-cookies] [--expect-rev REVISION]| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
<id> | string | yes | none | The connection (bic_…). |
--name NAME | string | no | unchanged | Rename the connection. |
--url URL | string | no | unchanged | The new address of Grafana, or of the Tableau server or pod. |
--org-id N | integer | no | unchanged | The Grafana organization the token belongs to. |
--tenant-id ID | string | no | unchanged | The Power BI connection's Microsoft Entra tenant. |
--client-id ID | string | no | unchanged | The Power BI connection's Application (client) ID, or the Tableau connected app's Client ID. |
--site SITE | string | no | unchanged | The Tableau connection's site content URL. Not with --default-site. |
--default-site | boolean | no | off | Tableau Server: sign in to the default site. Not with --site. |
--secret-id ID | string | no | unchanged | The Tableau connected app's Secret ID. |
--username USER | string | no | unchanged | The Tableau user the screens' views are shown as, or the web connection's service account. |
--token-file FILE | string | no | unchanged | Grafana: read the service-account token from this file, or - for stdin; it replaces the stored token. At most one of --token-file, --secret-file, --password-file and --clear-password. |
--secret-file FILE | string | no | unchanged | Power BI or Tableau: read the secret value from this file, or - for stdin; it replaces the stored secret. |
--login-mode MODE | string | no | unchanged | Web: how it signs in, auto, steps or none. |
--login-url URL | string | no | unchanged | Web: the https address of the site's sign-in page. A new origin needs --password-file in the same command, so the stored password is never sent to a page you did not give it. |
--password-file FILE | string | no | unchanged | Web: read the service account's password from this file, or - for stdin; it replaces the stored password. |
--clear-password | boolean | no | off | Web: remove the stored password. |
--totp-file FILE | string | no | unchanged | Web: read the authenticator key from this file, or - for stdin; it replaces the stored key. Not with --clear-totp. |
--clear-totp | boolean | no | off | Web: remove the stored authenticator key. Not with --totp-file. |
--steps FILE | string | no | unchanged | Web: replace the sign-in script, a JSON array of at most 30 steps, from a file or -. |
--cookies-file FILE | string | no | unchanged | Web: replace the cookie jar with one exported from a signed-in browser, from a file or - (the forms bi connection create web takes). Not with --clear-cookies. |
--clear-cookies | boolean | no | off | Web: remove the stored cookie jar. Not with --cookies-file. |
--expect-rev REVISION | integer | no | none | Refuse the change unless the connection is at this revision (revision_conflict, exit 6). |
screenrig bi connection update bic_01EXAMPLECONNECTION0000 --token-file new-token.txt
screenrig bi connection update bic_01EXAMPLECONNECTION0000 --password-file new-password.txt
screenrig bi connection update bic_01EXAMPLECONNECTION0000 --clear-totp --clear-cookies
screenrig bi connection update bic_01EXAMPLECONNECTION0000 --url https://grafana.example.com --token-file new-token.txt --name "Ops Grafana" --expect-rev 2At least one change is required, and an omitted secret is kept. A new address on another host, scheme or port needs --token-file (Grafana) or --secret-file (Tableau) in the same command: the stored secret is only sent to the address it was saved for. A new address, organization, tenant, app, site, user or secret clears last_test and retires every render cached for the connection's views: test it again. A change of credentials or sign-in settings lifts a stopped web session.
bi connection test#
Check the credentials: Grafana's token and Image Renderer, Power BI's app and its workspaces, Tableau's sign-in, or a web connection's sign-in.
bi connection test <id>| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
<id> | string | yes | none | The connection (bic_…). |
screenrig bi connection test bic_01EXAMPLECONNECTION0000Grafana: token (Grafana accepts it) and image_renderer (the plugin is listed; Grafana without it only warns, because a remote rendering service does not show as a plugin). Power BI: token (Microsoft Entra issued one for the app) and workspaces (the workspaces the app can see; none fails, and a refusal names the Developer tenant settings and the app's Member or Admin role in the workspace). Tableau: signin as the connection's user with a content-read token, followed by a sign-out. Web: login signs in as the service account and draws its sign-in page; a web connection that signs nothing in has no sign-in to test, so it answers a warning, and bi view test checks its cookies. A refusal is a failed check that carries the vendor's own answer, and the result is stored as last_test. The test does not judge a Tableau domain allowlist, capacity, row-level security or a dashboard's permissions: bi view test checks a view for real.
bi connection browse#
List what a connection can show: Grafana dashboards and panels, Power BI workspaces and reports, or Tableau views.
bi connection browse <id> [--query TEXT] [--dashboard UID] [--workspace ID]| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
<id> | string | yes | none | The connection (bic_…). |
--query TEXT | string | no | none | Only dashboards, workspaces, reports or views whose name matches, at most 200 characters. |
--dashboard UID | string | no | none | Grafana: list this dashboard's panels instead. Not with --workspace. |
--workspace ID | string | no | none | Power BI: list this workspace's reports instead, by its GUID. Not with --dashboard. |
screenrig bi connection browse bic_01EXAMPLECONNECTION0000 --query lobby
screenrig bi connection browse bic_01EXAMPLECONNECTION0000 --dashboard abc123
screenrig bi connection browse bic_01EXAMPLECONNECTION0000 --workspace f089354e-8366-4e18-aea3-4cb4a3a50b48 --query salesdata.items lists, for Grafana, the uid, title, folder and tags of each dashboard the token can show, or with --dashboard the id, title and type of its panels (rows are flattened, so a panel inside a collapsed row is listed); for Power BI the id and name of each workspace the app can see, or with --workspace the id, name and embed_url of its reports; for Tableau the path, as Workbook/View, and name of each view the connection's user can see. Use these values with bi view create. A web connection lists nothing: each web view takes the address of its page.
bi connection delete#
Delete a connection no view uses.
bi connection delete <id> [--expect-rev REVISION]| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
<id> | string | yes | none | The connection (bic_…). |
--expect-rev REVISION | integer | no | none | Refuse the delete unless the connection is at this revision (revision_conflict, exit 6). |
screenrig bi connection delete bic_01EXAMPLECONNECTION0000While views use it the answer is resource_conflict (exit 5), naming them: delete those views first. The answer is data.id and data.deleted true.
BI views
A view is one dashboard or panel of a Grafana connection, one report of a Power BI workspace, one view of a Tableau site, one page of a web connection, or a public link that needs no connection: a Grafana public dashboard, a Power BI Publish to web link or a Tableau Public viz. A view ID starts biv_, and a view plays only on screens of its own project.
Put the view's embed_url in an iframe primitive with content_fit fill and publish as usual: the playlist holds no credential. Grafana and web views are drawn on the server as an image every --refresh and shared by every screen of the same size, so ten lobby screens make one render and the screen never talks to the system; the last good image stays on glass while a capture fails. A Power BI report and a Tableau view embed with a view-only token the server generates and renews, and the screen never holds the secret. A picture is drawn only while a screen's manifest names the view.
Reading needs Read access, and every change needs Manage access. Each target flag belongs to one kind of connection, and bi connection browse ID lists the values to use.
bi view create#
Add a view of a connection's dashboard, panel, report or Tableau view, or of a public link.
bi view create (--connection-id ID (--url URL | --dashboard UID | --workspace ID --report ID | --view WORKBOOK/VIEW)
| --public-url URL) [--name NAME] [--refresh DURATION] [--fit contain|cover|fill] [--rotate DURATION]
[--panel ID] [--from TIME] [--to TIME] [--var NAME=VALUE]... [--theme dark|light] [--timezone ZONE]
[--page NAME]... [--all-pages] [--rotate-sheets] [--wait-for CSS] [--wait-ms MS] [--clip CSS]| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
--connection-id ID | string | without --public-url | none | The connection (bic_…) to show something of. |
--url URL | string | one target | none | A dashboard address on the connection's Grafana host, a Power BI report address, a Tableau view address or, for a web connection, the page's https address on a public host. The rest of the target is read from it, so it takes none of --panel, --from, --to, --var, --theme, --timezone, --page or --all-pages. |
--dashboard UID | string | one target | none | Grafana: the dashboard's uid, the part after /d/ in its address. |
--workspace ID | string | one target | none | Power BI: the workspace ID, with --report. |
--report ID | string | with --workspace | none | Power BI: the report ID, with --workspace. |
--view WORKBOOK/VIEW | string | one target | none | Tableau: the view, the names after /views/ in its address (bi connection browse lists them). |
--public-url URL | string | one target | none | A Grafana public dashboard link, a Power BI Publish to web link or a Tableau Public viz address. It needs no connection and plays live from its host. Give it alone, with --name, --refresh, --fit, --rotate-sheets and --rotate. |
--name NAME | string | no | from the target | 1 to 80 characters. |
--refresh DURATION | string | no | 5m | Grafana: how often the image is drawn again, 30s to 24h. Web: how often the page is drawn again, 60s to 24h. Power BI and Tableau: how often the report or view refreshes its data, 60s to 24h, or 0 for none. Give a duration such as 30s, 5m or 1h, or a number of seconds. |
--fit FIT | string | no | contain | Grafana and web: how the image fills the screen, contain, cover or fill. |
--rotate DURATION | string | no | none | Power BI: how long each page shows, 10s to 1h; needed with two or more --page or with --all-pages. Tableau: how long each sheet shows; needed with --rotate-sheets. |
--page NAME | string | no | none | Power BI: a page to show, by name or display name. 1 to 200 characters. Repeatable; the pages show in this order. |
--all-pages | boolean | no | off | Power BI: rotate through every visible page, with --rotate. |
--rotate-sheets | boolean | no | off | Tableau: turn the workbook's published sheets, with --rotate. |
--panel ID | string | no | the whole dashboard | Grafana: show this one panel instead of the whole dashboard. A whole number, as in the address's viewPanel. |
--from TIME | string | no | none | Grafana: start of the time range, such as now-6h, now/d or an epoch in milliseconds. |
--to TIME | string | no | none | Grafana: end of the time range, such as now, now/d or an epoch in milliseconds. |
--var NAME=VALUE | string | no | none | Grafana: a dashboard variable. NAME may carry a var- prefix and a value is at most 200 characters. Repeatable. |
--theme THEME | string | no | dark | Grafana theme, dark or light. |
--timezone ZONE | string | no | none | Grafana: time zone for the dashboard, such as Europe/Paris, utc or browser. |
--wait-for CSS | string | no | none | Web: a CSS selector of an element that shows when the page is ready, and only when it is signed in. The capture waits for it and fails with bi_web_timeout when it never shows. |
--wait-ms MS | integer | no | none | Web: milliseconds to wait after the page is ready, for late charts, 0 to 10000. |
--clip CSS | string | no | the whole page | Web: a CSS selector of the part of the page to draw. |
screenrig bi view create --connection-id bic_01EXAMPLECONNECTION0000 --url 'https://grafana.example.com/d/abc123/lobby?orgId=1&viewPanel=4' --refresh 5m
screenrig bi view create --connection-id bic_01EXAMPLECONNECTION0000 --dashboard abc123 --panel 4 --from now-6h --to now --var host=web1 --theme light --name "Web CPU"
screenrig bi view create --public-url https://grafana.example.com/public-dashboards/TOKEN --name "Public status"
screenrig bi view create --connection-id bic_01EXAMPLECONNECTION0000 --workspace f089354e-8366-4e18-aea3-4cb4a3a50b48 --report 5b218778-e7a5-4d73-8187-f10824047715 --page Overview --page Detail --rotate 30s --name "Sales rotation"
screenrig bi view create --connection-id bic_01EXAMPLECONNECTION0000 --view Sales/Overview --rotate-sheets --rotate 30s --refresh 0 --name "Sales sheets"
screenrig bi view create --connection-id bic_01EXAMPLECONNECTION0000 --url https://app.example.com/dashboards/42 --refresh 5m --wait-for '#dashboard.loaded' --wait-ms 1500 --clip '#chart-grid'Give exactly one target: --url, --dashboard, --workspace with --report, --view or --public-url. The answer carries data.embed_url. Run bi view test next.
Grafana: --url reads orgId, viewPanel or panelId, from, to, var-*, theme and timezone from the address. The image is drawn through Grafana's render service and shared by every screen of the same size, and a screen keeps the last image, with the render's time in a corner, while Grafana is down. A public dashboard link plays live from Grafana, which must allow embedding (allow_embedding = true in its settings): bi view test checks it.
Power BI: --url takes a report address copied from Power BI, https://app.powerbi.com/groups/WORKSPACE/reports/REPORT, with an optional /ReportSection page; or give --workspace and --report. Two or more pages need --rotate, and --rotate needs two or more pages or --all-pages. --refresh 0 suits a DirectQuery or automatic-page-refresh report that updates itself. --fit does not apply. A Publish to web link shows the report to anyone with the link and plays as Power BI serves it, reloaded every --refresh, without page rotation.
Tableau: --url takes a view address copied from Tableau, https://HOST/t/SITE/views/WORKBOOK/VIEW, Tableau Cloud's https://HOST/#/site/SITE/views/WORKBOOK/VIEW, or just WORKBOOK/VIEW; the address must be on the connection's host and site. --rotate-sheets and --rotate each need the other. --fit does not apply. The screens must reach the Tableau host and accept its third-party cookies, and the view's embed_origin must be in the connected app's domain allowlist. A Tableau Public viz (--public-url https://public.tableau.com/app/profile/USER/viz/WORKBOOK/VIEW, or its /views/ address) needs no connection and no token, and --rotate-sheets works there too.
Web: --url is the page's address, and --wait-for, --wait-ms and --clip apply only to a web view. The last good image stays on glass when a capture fails, and status.last_error says why: bi_web_login_failed, bi_web_otp_required, bi_web_session_expired, bi_web_login_paused, bi_web_timeout, bi_web_navigation_failed or bi_web_blocked.
bi view list#
List this project's BI views with their target, cadence and status.
bi view listNo parameters.
screenrig bi view listdata.items holds every view of the project, each with its embed_url.
bi view show#
Inspect one view, its embed_url and how it last fared on glass.
bi view show <id>| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
<id> | string | yes | none | The view (biv_…). |
screenrig bi view show biv_01EXAMPLEVIEW0000000000The answer carries kind, name, connection_id (absent for a public link), target (view and rotate_sheets for Tableau), refresh_s, rotate_s, fit, status, embed_url and revision; a web view also carries wait_for, wait_ms and clip. status holds last_ok_at and last_error with a code and a detail: bi_upstream_refused when Grafana refused the token, bi_upstream_unavailable when it could not render, or one of the bi_web_* codes of a web view.
bi view update#
Change a view's name, target, cadence or fit.
bi view update <id> [--name NAME] [--refresh DURATION] [--fit contain|cover|fill] [--rotate DURATION]
[--url URL | --dashboard UID | --workspace ID | --view WORKBOOK/VIEW | --public-url URL] [--report ID]
[--page NAME]... [--all-pages] [--rotate-sheets] [--panel ID] [--from TIME] [--to TIME]
[--var NAME=VALUE]... [--theme dark|light] [--timezone ZONE] [--wait-for CSS | --clear-wait-for]
[--wait-ms MS] [--clip CSS | --clear-clip] [--expect-rev REVISION]| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
<id> | string | yes | none | The view (biv_…). |
--name NAME | string | no | unchanged | Rename the view. |
--url URL | string | no | unchanged | A dashboard, report or Tableau view address, or a web view's page address; replaces the whole target. Not with the other target flags. |
--dashboard UID | string | no | unchanged | Grafana: show this dashboard; replaces the whole target. |
--workspace ID | string | no | unchanged | Power BI: show a report of this workspace, with --report; replaces the whole target. |
--report ID | string | no | unchanged | Power BI: show this report, in --workspace or the current one. |
--view WORKBOOK/VIEW | string | no | unchanged | Tableau: show this view; replaces the whole target. |
--public-url URL | string | no | unchanged | A public link; replaces the whole target. |
--rotate-sheets | boolean | no | off | Tableau: turn the workbook's published sheets, with --rotate. |
--page NAME | string | no | unchanged | Power BI: the pages to show, by name or display name. Repeatable; it replaces the current pages. |
--all-pages | boolean | no | off | Power BI: rotate through every visible page. |
--rotate DURATION | string | no | unchanged | Power BI: how long each page shows, 10s to 1h, or 0 for one page. Tableau: how long each sheet shows, or 0 to stop turning them. |
--panel ID | string | no | unchanged | Grafana: show this one panel. |
--from TIME | string | no | unchanged | Grafana: start of the time range. |
--to TIME | string | no | unchanged | Grafana: end of the time range. |
--var NAME=VALUE | string | no | unchanged | Grafana: set a dashboard variable. Repeatable; it sets one variable and keeps the others. |
--theme THEME | string | no | unchanged | Grafana theme, dark or light. |
--timezone ZONE | string | no | unchanged | Grafana: time zone for the dashboard. |
--refresh DURATION | string | no | unchanged | How often the image is drawn again or the report refreshes: Grafana 30s to 24h; web 60s to 24h; Power BI and Tableau 60s to 24h, or 0 for none. |
--fit FIT | string | no | unchanged | Grafana and web: how the image fills the screen, contain, cover or fill. |
--wait-for CSS | string | no | unchanged | Web: the element that shows when the page is ready and signed in. Not with --clear-wait-for. |
--clear-wait-for | boolean | no | off | Web: stop waiting for an element. Not with --wait-for. |
--wait-ms MS | integer | no | unchanged | Web: milliseconds to wait after the page is ready, 0 to 10000; 0 removes the wait. |
--clip CSS | string | no | unchanged | Web: the part of the page to draw. Not with --clear-clip. |
--clear-clip | boolean | no | off | Web: draw the whole page again. Not with --clip. |
--expect-rev REVISION | integer | no | none | Refuse the change unless the view is at this revision (revision_conflict, exit 6). |
screenrig bi view update biv_01EXAMPLEVIEW0000000000 --wait-for '#dashboard.loaded' --wait-ms 2000
screenrig bi view update biv_01EXAMPLEVIEW0000000000 --clear-wait-for --clear-clip
screenrig bi view update biv_01EXAMPLEVIEW0000000000 --theme light --var host=web2
screenrig bi view update biv_01EXAMPLEVIEW0000000000 --dashboard def456 --panel 2 --expect-rev 3
screenrig bi view update biv_01EXAMPLEVIEW0000000000 --page Overview --page Detail --rotate 45s
screenrig bi view update biv_01EXAMPLEVIEW0000000000 --view Sales/DetailAt least one change is required. --url, --dashboard, --workspace and --public-url replace the whole target, while --panel, --from, --to, --var, --theme and --timezone change the view's current Grafana target, --report, --page and --all-pages the Power BI one, and --view and --rotate-sheets the Tableau one. --page replaces the page list; to clear it give --workspace and --report again with --rotate 0. --rotate 0 alone stops a Tableau view from turning its sheets. --url and --public-url take no other target flag but --rotate-sheets, and a view of a public link changes its target only with --public-url. A new target clears the status and retires its cached renders, and screens pick the change up at their next refresh without a republish. A view keeps its connection and kind.
bi view test#
Check a view for real: a Grafana or web render, a Power BI embed token, a Tableau lookup, or a public link.
bi view test <id> [--output FILE [--width PIXELS] [--height PIXELS]]| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
<id> | string | yes | none | The view (biv_…). |
--output FILE | string | no | none | Grafana or web: save the rendered PNG here instead of running the checks. A Power BI or Tableau view and a public link have none (not_found). |
--width PIXELS | integer | no | 1920 | Width of the saved image, 1 to 10000. Needs --output. |
--height PIXELS | integer | no | 1080 | Height of the saved image, 1 to 10000. Needs --output. |
screenrig bi view test biv_01EXAMPLEVIEW0000000000
screenrig bi view test biv_01EXAMPLEVIEW0000000000 --output lobby.png --width 1920 --height 1080Grafana: a connection view renders for real, outside the shared cache and without touching the view's status. data.ok is false with Grafana's reason when it refuses the token, has no renderer or does not know the dashboard; a failed test is data, exit 0. Web: a connection view is drawn once in the server's browser (render), outside the shared cache, and a failed draw names why. Open the saved PNG and look before publishing. For a public link the test fetches the page and checks that Grafana lets the view's embed page frame it.
Tableau: a connection view signs in as the connection's user and looks the view up (signin, view); a view the user cannot see, or a name with the wrong case, is a failed view check naming the path. A Tableau Public view asks Tableau Public whether the workbook exists. Power BI: a connection view reads the report (report) and generates a real view-only embed token for it (embed_token); Power BI's own reason is shown when it refuses, such as a dataset with row-level security, a 401 or 403 (tenant setting or workspace role) or a report the app cannot see. A Publish to web link is fetched and its framing headers read.
The test does not judge what the picture shows, the pages the view names, capacity or a Tableau domain allowlist. data holds at, ok and checks, each check with name, ok, an optional warn and a detail; a Grafana or web render adds width, height and bytes. With --output, data holds id, file, bytes, width and height instead.
bi view delete#
Delete a view.
bi view delete <id> [--expect-rev REVISION]| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
<id> | string | yes | none | The view (biv_…). |
--expect-rev REVISION | integer | no | none | Refuse the delete unless the view is at this revision (revision_conflict, exit 6). |
screenrig bi view delete biv_01EXAMPLEVIEW0000000000
screenrig bi view delete biv_01EXAMPLEVIEW0000000000 --expect-rev 3A screen still showing the view's embed_url answers not_found until its playlist changes. The answer is data.id and data.deleted true.