Command-Line Options
The server accepts two kinds of command-line options. Startup options
configure the server process that you start: they set the configuration file,
logging, the data directory, the HTTP listener, and the datastore connection,
and they take priority over environment variables and the matching settings in
the configuration file. Administrative options run a single task against the
server's authentication store, such as creating a user or a token, and exit
without starting the server; pass the same -config flag that the running
server uses, so that the command opens the same data directory. When the
server starts with a -data-dir flag, also pass the same -data-dir value to
each administrative command, because the flag takes priority over the
data_dir setting in the configuration file. The server
records each administrative change in the
audit log under the cli actor.
The following sections group the options by function. The first three
sections list startup options, apart from the -check-config and
-health-check checks in General Options, which also exit without starting
the server; the remaining sections list administrative options:
- General Options
- HTTP Server Options
- Database Connection Options
- Token Management Options
- User Management Options
- Group Management Options
- Privilege Management Options
- Token Scope Options
- Audit Log Options
The token, user, group, privilege, and token scope flags are useful for
scripted setup and for creating the first administrator account. After you sign
in, the Users, Groups, Permissions, and Tokens tabs of the
Administration console provide the same management on screen; see
Managing Accounts.
General Options
The general options set the configuration file path, debug logging, the data directory, and the trace file, and run the one-off configuration check, health check, and OpenAPI export.
| Flag | Description |
|---|---|
-config string |
Path to configuration file |
-check-config |
Validate the configuration file, then exit without starting the server; see Upgrading the Workbench |
-debug |
Enable debug logging |
-data-dir string |
Data directory for the authentication database |
-openapi string |
Write the OpenAPI specification of the REST API to the given file, then exit without starting the server |
-health-check host:port |
Check that a TCP listener accepts connections at the given address, then exit with status 0, or 1 if it does not; the example Docker Compose files use it as the server health check |
-trace-file string |
Path to MCP trace file |
HTTP Server Options
The HTTP server options configure the listen address and TLS certificate files for encrypted connections.
| Flag | Description |
|---|---|
-addr string |
HTTP address (default: :8080) |
-tls |
Enable TLS/HTTPS |
-cert string |
Path to TLS certificate file |
-key string |
Path to TLS key file |
-chain string |
Path to TLS certificate chain |
Database Connection Options
The database connection options set the host, port, credentials, and SSL mode for the PostgreSQL connection.
| Flag | Description |
|---|---|
-db-host string |
Database host |
-db-port int |
Database port |
-db-name string |
Database name |
-db-user string |
Database user |
-db-password string |
Database password |
-db-password-file string |
Path to DB password file, read at startup only; overrides the configured password |
-db-sslmode string |
SSL mode |
Connection Security Options
The connection security option sets the directory that monitored connections' SSL files must be in.
| Flag | Description |
|---|---|
-connection-ssl-cert-dir string |
Absolute path of the directory that monitored connections' SSL certificate, key and root certificate files must be in; sets connection_security.ssl_cert_dir, and an empty value clears a directory set in the configuration file |
Token Management Options
Use the token management options to create, remove, list, and annotate service tokens.
| Flag | Description |
|---|---|
-add-token |
Add a new service token |
-remove-token string |
Remove token by ID or hash |
-list-tokens |
List all service tokens |
-token-note string |
Annotation for new token |
-token-expiry string |
Token expiry duration |
-user string |
Owner username for the token |
User Management Options
The user management options add, update, delete, enable, and disable user and service accounts, and link accounts to identities at a single sign-on provider. The Managing Single Sign-On page describes how to link and unlink federated accounts.
| Flag | Description |
|---|---|
-add-user |
Add a new user |
-update-user |
Update an existing user |
-delete-user |
Delete a user |
-list-users |
List all users |
-enable-user |
Enable a user account |
-disable-user |
Disable a user account |
-add-service-account |
Add a service account |
-link-oidc-user |
Link an existing account to an OIDC identity; requires -username, -issuer, and -subject |
-unlink-oidc-user |
Unlink an account from its OIDC identity, returning it to local authentication |
-issuer string |
OIDC issuer URL, exactly as the server logged it; used with -link-oidc-user |
-subject string |
OIDC subject (the sub claim), exactly as the server logged it; used with -link-oidc-user |
-relink |
Allow -link-oidc-user to move an account that is already linked to a different identity |
-restore-password |
Let -unlink-oidc-user keep the password the account had before it was linked, instead of making it unusable |
-username string |
Username for user commands |
-password string |
Password for user commands; deprecated because the password appears in the shell history and process listings |
-password-file string |
Path to a file containing the password for user commands; recommended for production use |
-full-name string |
Full name for the user |
-email string |
Email address for the user |
-user-note string |
Annotation for new user |
Group Management Options
The group management options create, delete, and list RBAC groups, and manage group membership and superuser status.
| Flag | Description |
|---|---|
-add-group |
Add a new RBAC group |
-delete-group |
Delete an RBAC group |
-list-groups |
List all RBAC groups |
-list-members |
List the members of a group |
-add-member |
Add a user or group to a group |
-remove-member |
Remove a member from a group |
-group string |
Group name for group commands |
-group-description string |
Group description for -add-group |
-member-group string |
Member group for nesting |
-set-superuser |
Set superuser status |
-unset-superuser |
Remove superuser status |
Privilege Management Options
The privilege management options grant, revoke, register, and list MCP privileges and connection access levels.
| Flag | Description |
|---|---|
-grant-privilege |
Grant an MCP privilege |
-revoke-privilege |
Revoke an MCP privilege |
-grant-connection |
Grant connection access |
-revoke-connection |
Revoke connection access |
-list-privileges |
List MCP privileges |
-show-group-privileges |
Show group privileges |
-register-privilege |
Register a new privilege |
-privilege string |
MCP privilege identifier |
-privilege-type string |
Privilege type |
-privilege-description string |
Description |
-privilege-public |
Mark a privilege registered with -register-privilege as public, so a user can use it without group membership |
-connection int |
Connection ID |
-access-level string |
Access level (default: read) |
Token Scope Options
The token scope options set, clear, and display the connections and tools a service token can access.
| Flag | Description |
|---|---|
-scope-token-connections |
Set connection scope |
-scope-token-tools |
Set MCP tool scope |
-clear-token-scope |
Clear all scope restrictions |
-show-token-scope |
Show current token scope |
-token-id int |
Token ID for scope commands |
-scope-connections string |
Connection ID list |
-scope-tools string |
Tool name list |
Audit Log Options
The audit log records every change to users, groups, tokens, and privileges;
the Managing the Audit Log
page describes the events and how to read them. The audit log options read and
verify the log. The -rechain-audit-log option either re-hashes an inherited
log or re-anchors a log that no longer verifies; a re-anchor leaves the
existing events as they are and appends an anchor event.
| Flag | Description |
|---|---|
-list-audit |
List RBAC audit log events |
-verify-audit-log |
Verify the audit log hash chain |
-rechain-audit-log |
Re-hash an inherited audit log, or re-anchor one that no longer verifies |
-confirm-rechain |
Confirm -rechain-audit-log without an interactive prompt |
-previous-secret-file string |
Secret file the older audit events were written under, needed by -confirm-rechain to re-anchor them |
-audit-actor string |
Filter events by actor name |
-audit-action string |
Filter events by action |
-audit-target-type string |
Filter events by target type |
-audit-target-id int |
Filter events by target ID |
-audit-outcome string |
Filter events by outcome |
-audit-since string |
Earliest event time to show |
-audit-until string |
Latest event time to show |
-audit-limit int |
Maximum events to show (default: 50) |
-json |
Emit output as one JSON object per line |