Server command line

Every command of OpenBI.Server.exe, OpenBI Server’s command line, generated from the help the program itself prints. Everything IT does on the server can be done here, without a browser, by a person or by their agent.

Running a command

On Windows, open a Command Prompt as administrator on the server, in the folder OpenBI Server is installed in. In PowerShell, start each command with .\OpenBI.Server.exe.

cd "C:\Program Files\OpenBI Server"
OpenBI.Server.exe help

On a Mac, the command line is openbi-server, with the same commands. Run it in Terminal with sudo, from any folder. help, version and sbom need no sudo.

sudo openbi-server doctor

Help for one command: add --help anywhere in it, such as OpenBI.Server.exe workspace member add --help. It prints that command’s lines and runs nothing.
For agents and scripts: --json gives the same answer as JSON.
Dry runs: the setups (iis, https, firewall, cluster create, cluster join, database move, lake add, lake setup, lake remove, lake encryption off) and billing domain list their steps, done or still to do, and change nothing until you add --apply.
Secrets from the input: a command that needs a secret you didn’t give it (a licence key, a client secret, a database connection) asks for it, typed hidden, or reads it from the input when it is piped in, so it stays out of your command history. A data source’s and a lake’s secrets, and a cluster’s key, are never taken as arguments at all.
Exit codes: 0 when all is well; 1 when the command refused or failed (also when it couldn’t open the server’s data folder without administrator rights), or a check found warnings; 2 when a check found something to fix, a setup’s step failed, a change to the machine (a service, IIS, HTTPS, the firewall) was run without administrator rights, or there is no such command. sbom has its own (see The bill of materials).

Below, each command is written without the program’s name: doctor is OpenBI.Server.exe doctor on Windows and sudo openbi-server doctor on a Mac. Replace each <…> with your own value.

OpenBI Server 0.1.49: 129 commands in 18 areas, as OpenBI.Server.exe help gives them.

Status and checks

The server at a glance, everything checked, its version and its bill of materials.

status: The service, the domains' licences, IIS and HTTPS at a glance.
doctor: Checks everything this server needs, each problem with the command that fixes it.
version: This program's version.
sbom [--verify]: The bill of materials installed with the server (sbom.cdx.json, CycloneDX 1.5, and sbom.html beside the program).

Domains and licences

One licence per domain: the server answers only for its domains. A seat licence's seats, its subscription and its domain too (see Buy OpenBI Server and Change domain).

domain add <domain> --key <license key>: Adds a domain: its licence (from your OpenBI seller) activated for it here.
domain list: The domains and their licences' state.
domain remove <domain>: Frees the domain's licence from this server (to move it to another).
license seats: The seats: how many are in use of how many (counts only - no one's name).
license fingerprint: This machine's fingerprint (read only: an internal licence's machines are registered with it beforehand).
billing [--domain <d>] [--check]: The seat licence's subscription, read only: its plan, seats, next charge, a pending change, the trial's end and a failed payment (--check: the licence read again first).
billing domain <new domain> [--transition-days N] [--from <d>] [--apply]: The seat licence's domain changed (a real one after a made-up openbi.home.arpa, or a new name).
billing domain --end-transition [--apply]: The old names stop leading here now.
refresh: Every licence's heartbeat and a new licence file, now (with --workspace and --item: that model's data, below).

The service and its log

The Windows service OpenBIServer (a launchd daemon on a Mac).

service status|start|stop|restart: The service OpenBIServer: its state, or start, stop or restart it.
logs [--lines N]: The server's latest log lines (its data folder's logs\).

Where people sign in: OpenBI Accounts on this machine, or your own OpenID Connect provider. The service takes a change when it restarts.

signin use-accounts --server-url https://bi.<domain> [--server-url https://bi.<other domain> …]: Registers this server in OpenBI Accounts on this machine under each name it answers to, and signs people in there (signed in under one name, the others sign them in at once).
signin set --authority <https://…> --client-id <id> [--client-secret <secret>] [--studio-client-id <id>] [--studio-scope "<scopes>"] [--audience <audience>]: Signs people in with your own OpenID Connect provider instead (Entra ID: https://login.microsoftonline.com/<tenant id>/v2.0); the --studio options are OpenBI Studio's registration there.
signin status | signin clear: Where people sign in now, and whether the provider answers; or the sign-in removed.

OpenBI Accounts

OpenBI Accounts' own commands, after accounts: its address, people, e-mail, the servers that sign people in there, and where its records are kept.

accounts service status|start|stop|restart: The service OpenBIAccounts: its state, or start, stop or restart it.
accounts logs [--lines N]: OpenBI Accounts' latest log lines.
accounts setup --public-url https://accounts.<domain> --name "<Company AS>" [--forget-former-urls] [--former-urls <url,url|none>]: Its public address (behind IIS, under a licensed domain) and whose sign-in it is.
accounts status: Its address (and those it had before), database, people and servers.
accounts user invite --email <e-mail> [--name "<name>"] [--admin] [--no-mail] [--domain <licensed domain>]: Makes their sign-in and e-mails them the invitation (with e-mail set up), and prints its link: it works once, for 7 days.
accounts user invite --pending [--replace-working] [--include-before-0136]: A new invitation by e-mail for everyone not set up yet whose invitation no longer works (expired, used, ended) or never reached them (its e-mail failed, its link went to no one).
accounts user list [--pending]: Everyone (or only those not set up yet) and where each stands.
accounts user disable --email <e-mail> | accounts user enable --email <e-mail>: Stops someone signing in, or lets them again.
accounts user reset --email <e-mail>: A new invitation: new password and authenticator (a lost phone).
accounts user mail --email <e-mail>: The e-mails sent them (invitations, "Forgot password?", workspaces' notices) and what came of each - sent, failed and why, not sent, held back, no account - each with the mail service's ids under it.
accounts mail set --graph --tenant <tenant id> --client-id <app id> --from <mailbox> [--secret <secret>]: Microsoft 365: an app registration that may send as that mailbox only (Exchange Online's "Application Mail.Send" role scoped to it).
accounts mail set --smtp --host <host> [--port 587] [--user <user>] --from <address> [--password <password>]: Any SMTP server (STARTTLS); the password asked for or piped in, as above.
accounts mail set --folder <path> --from <address>: .eml files into a folder (to try it; or a pickup folder).
accounts mail set … [--copy-to <address>] [--copy-kinds alert,refresh-failed,backup-failed,test]: A copy of each sign-in e-mail to that address, for support - invitations, sign-in resets, access given, a role changed, access ended.
accounts mail status | accounts mail test --to <e-mail> | accounts mail clear: E-mail's settings; a test e-mail, which also checks the sender's domain (SPF, DKIM, DMARC); or e-mail turned off (invitations become links you send yourself).
accounts mail check: Only that check of the sender's domain (no e-mail sent).
accounts client add --id <id> --url https://bi.<domain>: Registers an OpenBI Server; prints its secret once.
accounts client list | accounts client remove --id <id>: The servers registered to sign people in here (openbi-studio is OpenBI Studio itself, registered by OpenBI Accounts), or one removed.
accounts database status: Where OpenBI Accounts' records are.
accounts database move --provider <sqlserver|postgres|sqlite> --connection "<…>" [--apply]: Lift and shift: copies, checks every table, then switches (a dry run without --apply).
accounts database back: Returns to the database used before the last move.

Workspaces and people

Only the server's administrators make workspaces; a workspace's Admins (or the server's administrators) say who may use it, and who of its Viewers may see formulas.

workspace create --name "<name>" [--domain <domain>] [--description "<text>"]: A new workspace under one of the server's domains (--domain, when it has more than one).
workspace list [--all] | workspace show --workspace "<name>" [--pending]: The workspaces (--all: the archived ones too); or one workspace's people, each with their role and where their sign-in stands (--pending: only those not set up yet).
workspace member add --workspace "<name>" --email <e-mail> --role viewer|contributor|member|admin [--name "<name>"] [--no-mail]: Gives someone a role in a workspace: someone new is invited by e-mail, someone who signs in already is told; again with another role changes theirs.
workspace member resend --workspace "<name>" [--pending] [--email <e-mail>] [--replace-working] [--include-before-0136] [--dry-run]: A new invitation by e-mail for its people not set up yet.
workspace member remove --workspace "<name>" --email <e-mail>: Takes someone out of a workspace.
workspace archive|restore --workspace "<name>": Closed to everyone and kept (never deleted: the audit).
formulas list --workspace "<name>" | formulas grant|revoke --workspace "<name>" --email <e-mail>: "Can see formulas" for a workspace's Viewers (Power BI's Build permission): measures' OAX in their reports' model, Excel and agents.

Administrators and the audit

The server's administrators manage every workspace; the audit says who did what.

admin add|remove --email <e-mail> | admin list: The server's administrators (every workspace).
audit [--workspace "<name>"] [--lines N]: Who did what, when.

AI agents (remote MCP)

People's own AI agents on the server: off until a server administrator turns it on and a workspace's Admins allow it in their workspace (see AI agents on the server).

mcp status: AI agents (MCP): on or off, the endpoint of each domain, the sign-in check, the allowed clients, connections and workspaces that allow agents.
mcp on | mcp off: Let people connect AI agents to this server (off by default).
mcp workspace on|off --workspace "<name>": A workspace lets agents in, or no longer (off until turned on).
mcp clients: The allowed clients (known ones on or off, redirect addresses added), whether apps may register themselves (dcr) or come by their metadata document (cimd), and the agents' apps OpenBI Accounts keeps.
mcp allow claude|chatgpt|local|copilot|vscode-web|cursor-web|inspector [--off]: A known app may connect, or no longer (--off): Claude (claude.ai and the Claude apps), ChatGPT, apps on the person's own computer (Claude Code, Cursor, VS Code), Microsoft Copilot Studio, VS Code for the web, Cursor's web agents, the MCP Inspector in a browser. The first three are on until turned off.
mcp allow --redirect "https://…" [--off]: Another client's redirect address (ending in /*: any path under it).
mcp allow --document "https://…" [--off]: Another app's metadata document (CIMD), by its exact address.
mcp dcr on|off | mcp cimd on|off: Apps registering themselves (RFC 7591) / by their metadata document.
mcp own-dax auto|guarded|open: An agent's own OAX (dax_query), anyone's, on any model.
mcp register --name "<app>" --redirect "https://…" [--redirect …] [--secret]: An app registered by you (Copilot Studio's manual sign-in: --secret, shown once).
mcp connections [--email <e-mail>] [--client <id>]: Who connected which agent, when, last used, calls in 7 days.
mcp revoke --email <e-mail> [--client <id>] | mcp revoke --client <id>: Disconnected: their consents and tokens revoked (stops within 30 s).
mcp block|unblock --client <id>: An app blocked (its connections disconnected) or let in again.

Excel passwords

The passwords Excel signs in with for Analyze in Excel (never their secrets).

excel-passwords list [--email <e-mail>] | excel-passwords revoke --email <e-mail>: People's Excel passwords (Excel's sign-in for Analyze in Excel; never the secrets); revoke: all of that person's, at once.

The server's records

Where the server keeps its records (SQLite in the data folder by default), and moving them to SQL Server or PostgreSQL (MySQL not from 0.1.46 on).

database status | database move --provider <sqlserver|postgres|sqlite> --connection "<…>" [--apply] | database back: Where the server's records are (SQLite in the data folder by default), lift and shift (without --connection it is asked for, or read from the input: its password in no history).

A failover cluster

Two or more servers serving the same domains behind a load balancer, sharing one database. create and join are dry runs until --apply.

cluster create --name <cluster> [--node <name>] [--apply]: This server the cluster's first node: its key made and shown once, the sign-in's keys, the credentials and what is published taken into the shared database.
cluster join <a node's address> [--node <name>] [--license-key <key>] [--cluster-key-file <file>] [--local-url <url>] [--domain <domain>] [--apply]: Makes this server a node of the cluster: the cluster's key asked for (or --cluster-key-file), a licence of its own for each domain, the cluster's database, OpenBI Accounts and sign-in taken.
cluster status: Each node (ready, draining, down; its content), who runs the jobs, what is refreshing.
cluster drain <node>: Takes a node out of the load balancer's rotation for patching: its readiness answers 503, what it is answering finishes, its jobs go to another node.
cluster resume <node>: Brings a drained node back into the rotation, once its content is current.
cluster forget <node>: A node gone for good, out of cluster status.

Publishing

What OpenBI Studio publishes, from the command line: each publish is a new version, never altered or deleted.

publish --workspace "<name>" --file <path.openbimodel> [--name "<item>"] [--message "<what changed>"] [--include-review-pages "<page>, <page>"] [--confirm-person-rows]: Publishes an .openbimodel file to a workspace as a new version of its item (the project's name by default). Plan review pages in the file are left out unless --include-review-pages names them; one whose plan has a row per customer or person also needs --confirm-person-rows.
items --workspace "<name>": What is published there, at which version; a live model with its source.
versions --workspace "<name>" --item "<item>": Every version: when, by whom, its size, SHA-256 and message.

Report PDFs

Whether a report's PDF keeps its links clickable (see Links in a PDF).

pdf links: Whether a PDF's links are clickable (on by default).
pdf links on|off: On, or off: a PDF then has its pages' words only (every node of a cluster within 5 seconds; in the audit).

Data sources and refresh

The server's credentials for a model's sources, refreshes, schedules and the Monitor's activities. A secret is read from the input, never given as an argument.

datasource list --workspace "<name>" --item "<item>": The sources the model reads, and the server's credentials' state.
datasource set --workspace … --item … --source "<name or key>" --auth windows|password|key|connectionString|anonymous|service-principal [--user <name or client id>] [--tenant <id>] [--trust-certificate yes|no] [--sslmode require|verify-ca|verify-full|prefer|disable]: The server's credentials for one of a model's sources: how it signs in, with the secret read from the input (typed hidden, or piped).
datasource test|clear --workspace … --item … --source "<name or key>" [--as <e-mail>]: test signs in to the source now, here, as this account (--as: a live model's, as that Viewer); clear removes the server's credentials for it.
refresh --workspace "<name>" --item "<item>": A refresh now, run here as this account (Windows sign-ins are this account's).
schedule show|set --workspace … --item … [--on|--off] [--daily|--weekly mon,wed] [--times 07:00,12:30] [--timezone "W. Europe Standard Time"] [--notify-contacts] [--no-notify-owner] [--emails a@x.no,b@y.no]: A model's refresh schedule: shown, or set (on or off, daily or on given days, its times and time zone, and whom a failed refresh is e-mailed to).
history --workspace … --item … [--lines N]: Its refreshes: when, how, how long, why one failed.
activities [--workspace "<name>"] [--status Failed] [--kind refresh|publish|export] [--hours 24]: The Monitor's activities, newest first; --workspace, --status, --kind and --hours filter them.
live --workspace … --item … [--viewers off|as-viewer|everyone]: Who of a live model's Viewers sees it.

Lakes

OpenBI Lake on the server: shared lakes, grants, maintenance, backups and restores. A secret is read from the input; a lake outside this machine is said so before anything is written there.

lake list: The lakes: shared ones and each workspace's own - their SQL names, where their catalogs and files are, their reader roles, their grants.
lake add --name <name> --url <lake://…> [--sql-name <sql_name>] [--catalog-user <user>] [--reader-user <role> | --make-reader] [--storage-auth key|connectionString|chain|anonymous] [--storage-user <key id>] [--retention <days>] [--maintenance HH:mm] [--apply]: A shared lake: a dry run says where it writes and what it signs in with.
lake rename --name <lake> [--to <new name>] [--sql-name <sql_name>]: The old names kept as aliases (projects, SQL clients).
lake setup-reader --name <lake> [--admin-user <role>]: A PostgreSQL catalog's reader role, made with the catalog's user or a PostgreSQL administrator's that may CREATEROLE (its password read from the input, used once, never kept); the lake's writer, which owns its schema and tables, grants on them.
lake migrate --name <lake> [--dry-run]: An older DuckLake's catalog upgraded once, a copy of it kept first.
lake test --name <lake>: Its tables listed with the server's credentials.
lake grant --name <lake> --workspace "<workspace>" [--write]: A shared lake for a workspace's items: to read (--write: and write).
lake revoke --name <lake> --workspace "<workspace>": Takes a shared lake away from a workspace.
lake credentials --name <lake> [--catalog-user <user>] [--reader-user <role>] [--storage-auth … --storage-user …]: A shared lake's credentials changed (the secrets read from the input).
lake settings --name <lake> [--retention <days>] [--maintenance HH:mm]: A shared lake's retention and maintenance time.
lake remove --name <lake> [--apply]: The server forgets a lake; its catalog and files stay where they are (never deleted: add it again at its address to use it, or delete them by hand).
lake maintain --name <lake> [--dry-run]: Old versions expired (never those kept refreshes read), small files merged, unread files deleted.
lake encryption off --name <lake> [--apply]: An existing lake on this server's own disk whose files are not encrypted (its catalog says so): its address then says so too, and its runs load no httpfs.
lake backup-key new --out <file>: A backup key (32 random bytes) written once to a file the administrator keeps apart; its fingerprint said.
lake backup --name <lake> --to <target> [--to-auth sas|key|connectionString|anonymous] [--to-user <key id>] [--key-file <file>]: Backs a lake up now, at its newest version: its catalog encrypted with the backup key, the files it reads that the target doesn't have yet copied once. Without --to, its schedule runs now.
lake backups --name <lake> --to <target> …: Its whole backups there, newest first.
lake verify --name <lake> --to <target> --backup <id> [--key-file <file>]: The backup decrypted, every file read and its SHA-256 checked, and (a SQLite catalog's) restored apart and each table's rows and checksum compared.
lake restore --name <lake> --from <target> --backup <id> --to <lake://…> [--storage-auth … --storage-user …] [--catalog-user <user>] [--key-file <file>] [--replace]: A new lake at that address from the backup, its files copied to its storage, then each table checked against the backup; never over a lake that is there without --replace.
lake backup-prune --name <lake> --to <target> [--keep <n>] [--keep-days <n>]: Older backups deleted, and only the files no remaining backup names (an immutable target keeps what its policy holds: said, not failed).
lake backup-schedule --name <lake> [--to <target> [--to-auth …] [--to-user …] [--key-file <file>] [--time HH:mm] [--keep <n>] [--keep-days <n>] [--emails a@b.no,c@d.no] | --off]: The lake backed up every day at that time (02:00 if none) by the server (a cluster's jobs node), then pruned as kept.
lake setup [--accept <finding,finding> [--extension <name>]] [--catalog server|cluster|postgres] [--catalog-server host:port/db] [--catalog-user <user>] [--storage <folder or share|s3://bucket/prefix?endpoint=…|az://container/prefix?account=…>] [--storage-auth …] [--storage-user …] [--retention <days>] [--maintenance HH:mm] [--skip-extensions] [--apply]: Once: DuckDB's extensions into the server's data folder (downloaded from DuckDB's own repository).
lake setup --export <empty folder> [--duckdb v2.0.0] [--platform windows_amd64|osx_arm64|linux_amd64] [--apply]: On a machine WITH internet and this OpenBI Server.
lake setup --from <folder> [--fingerprint <the export's>] [--accept <finding,finding> [--extension <name>]] [--apply]: On the server WITHOUT internet.

Engines

How many queries each engine runs at once. The values go to settings.json in the data folder; the service takes them when it restarts.

engine limits: Queries at once, one person's, the server's connections to each engine, idle time, a query's time limit, the answers kept.
engine limits [--max-queries <n|auto|0>] [--max-queries-per-user <n|auto|0>] [--connection-pool <n|auto|0>] [--idle-time <30m|1h|…>] [--query-timeout <90s|5m|auto|0>] [--result-cache <MB|off>]: Sets them (settings.json in the data folder); the service takes them when it restarts.
engine limits --max-queries <n|auto|0>: The queries one engine runs at once; the others wait their turn, in the order they came.
engine limits --max-queries-per-user <n|auto|0> (or --per-user): One person's queries at once in one engine (a page of many visuals takes turns with everyone else's).
engine limits --connection-pool <n|auto|0>: The server's connections to one engine for queries; requests past them wait in the server, which costs nothing.
engine limits --idle-time <duration>: How long an engine nobody uses stays loaded: 30m, 1h, 1h30m, 8h, 1d (1 minute to 30 days).

Gateways

OpenBI Gateway from the server: gateways, their members, and the models they refresh (see The OpenBI Gateway).

gateway list: The gateways, their members and workspaces.
gateway create --name <name> --workspace <workspace> [--workspace …] [--domain <domain>]: A new gateway for the workspaces named; its one-time code shown once.
gateway code --gateway <name> [--domain <domain>]: A one-time code (its first member, or another).
gateway show --gateway <name>: Its members and their connections.
gateway map --workspace <workspace> --item <item> --gateway <name> | gateway unmap --workspace … --item …: A model refreshed through the gateway, or no longer.
gateway check --workspace <workspace> --item <item> --gateway <name>: What it reads, and which member reaches it.
gateway grant|ungrant --gateway <name> --workspace <workspace>: A workspace given the gateway, or taken from it.
gateway member remove|disable|enable --gateway <name> --member <name>: A member removed (its key and tokens stop working), disabled or enabled.
gateway remove --gateway <name>: The gateway removed.
gateway jobs [--gateway <name>]: The gateways' recent jobs.

In front of it: IIS, HTTPS, the firewall

Dry runs until --apply. iis and firewall are Windows only; on a Mac the server is its own front door, and https letsencrypt gets its certificate.

iis setup --host <name> [--keep-timeout]: IIS as the server's front door on http://<name> (URL Rewrite, ARR, its own site); --keep-timeout leaves ARR's timeout (the whole server's) as it is.
iis status: The site, its bindings, the modules.
iis web-config [--apply]: Only the site's web.config as it should be.
https letsencrypt --host <name> --email <address> [--check-public-ip]: A Let's Encrypt certificate for https://<name> (win-acme: issues, installs, renews).
https redirect: http:// answered with a redirect to https:// (once the certificate is in place).
https status --host <name>: The certificate https://<name> gives, and until when.
https local [--domain <domain>] [--renew]: HTTPS under a made-up name (openbi.home.arpa: home.arpa is for private networks, RFC 8375), which no public authority vouches for.
firewall: Inbound TCP 80 and 443 open (the service's own port stays closed).

Last updated 6 November 2026 · OpenBI Server 0.1.49