dashboard

Create and configure a Portabase dashboard. New here? Follow Set up a dashboard.

`dashboard create`

Creates the dashboard folder with .env (including a random 64-character PROJECT_SECRET) and docker-compose.yml.

portabase dashboard create [OPTIONS] NAME

Option	Description	Default
`NAME`	Folder to create, e.g. `my-dashboard`. Required.	—
`--port <int>`	Web port published on the host (`HOST_PORT`). `PROJECT_URL` becomes `http://localhost:<port>`.	`8887`
`--tz <str>`	Timezone (`TZ`).	`Europe/Paris`
`--db-mode <mode>`	`external`, `internal` or `custom` (see below).	`external`
`-s, --start`	Start the dashboard right after creation.	`false`
`-f, --force`	Overwrite an existing folder without asking.	`false`
`-y, --yes`	Skip the "Apply this configuration?" confirmation.	`false`

Database modes

Mode	What you get
`external`	Recommended. A dedicated `postgres:17-alpine` container (`db`) in the same compose, with random credentials and a random host port (`PG_PORT`).
`internal`	The database embedded in the Portabase container. No extra service.
`custom`	Your own PostgreSQL. `DATABASE_URL` is built from `--db-*` (user and password are URL-encoded).

Example

portabase dashboard create my-dashboard

Non-interactive / CI example: see Concepts.

Setup wizard

In interactive mode, when no settings option was passed, the CLI asks "Configure API, MCP and authentication now?" (default: no). Answering yes walks you through:

API & MCP — REST API, OpenAPI / Swagger UI, MCP server.
Onboarding — skip the onboarding wizard; if skipped, the initial user's name, email and password.
Authentication — email/password login, self sign-up, passkeys.

Then the CLI shows the SUMMARY, asks for confirmation, writes the files and prints how to add single sign-on later.

`dashboard show`

Displays the dashboard's settings grouped by section (Network, API & MCP, Onboarding, Authentication) — secrets are masked — and the table of login providers with their callback URL.

portabase dashboard show <DASHBOARD_PATH>

`dashboard set` / `dashboard unset`

Change or reset one or more settings of an existing dashboard, then re-render .env and docker-compose.yml.

portabase dashboard set <DASHBOARD_PATH> KEY VALUE [KEY VALUE ...]
portabase dashboard unset <DASHBOARD_PATH> KEY [KEY ...]

unset removes the variable from .env, so the dashboard falls back to its default.

Key	Type	Environment variable	Default
`url`	`http(s)://host[:port]`	`PROJECT_URL`	`http://localhost:<port>`
`behind_proxy`	boolean	`TUSD_BEHIND_PROXY`	`false`
`trusted_domains`	comma-separated list	`TRUSTED_DOMAINS`	—
`api`	boolean	`API_ENABLED`	`false`
`openapi`	boolean	`OPENAPI_ENABLED`	`false`
`mcp`	boolean	`MCP_ENABLED`	`false`
`skip_onboarding`	boolean	`SKIP_ONBOARDING`	`false`
`admin_name`	text	`AUTH_DEFAULT_USER_NAME`	—
`admin_email`	text	`AUTH_DEFAULT_USER`	—
`admin_password`	strong password (secret)	`AUTH_DEFAULT_PASSWORD`	—
`password_auth`	boolean	`AUTH_EMAIL_PASSWORD_ENABLED`	`true`
`signup`	boolean	`AUTH_SIGNUP_ENABLED`	—
`passkey`	boolean	`AUTH_PASSKEY_ENABLED`	—
`account_linking`	boolean	`AUTH_ALLOW_LINKING`	—
`account_unlinking`	boolean	`AUTH_ALLOW_UNLINKING`	—
`sync_oidc_roles`	boolean	`AUTH_SYNC_OIDC_ROLES_ON_LOGIN`	—
`role_map`	`remote:portabase,...`	`AUTH_ROLE_MAP`	—
`allowed_group`	text	`ALLOWED_GROUP`	—

See Dashboard environment variables for details on each variable.

portabase dashboard set ./my-dashboard url https://backup.example.com behind_proxy true
portabase dashboard set ./my-dashboard api true mcp true
portabase dashboard unset ./my-dashboard trusted_domains
portabase restart ./my-dashboard

Changing url does not change the published port (HOST_PORT). Expose the dashboard behind a reverse proxy and set behind_proxy true.

Safety checks

The CLI refuses to write a configuration that would break your instance:

skip_onboarding true requires admin_email and admin_password.
admin_password must have at least 8 characters, a lowercase letter, an uppercase letter, a digit and a special character.
password_auth false is refused while no OIDC or OAuth provider is configured (it would lock everyone out).
Login providers require a public url — localhost and 127.0.0.1 are refused, since the identity provider must reach the callback.

Option	OIDC	OAuth	Description
`KIND`	Yes	Yes	`oidc` or `oauth`. Asked if omitted.
`PROVIDER_ID`	Yes	Yes	`oidc`: any slug (lowercase letters, digits, dashes, e.g. `keycloak`). `oauth`: one of `google`, `github`, `discord`, `apple`, `linkedin`, `x`, `reddit`. Asked if omitted.
`--issuer <url>`	Yes		Issuer / discovery URL (`http(s)://…`). Asked if omitted.
`--client <str>`	Yes	Yes	Client ID. Asked if omitted.
`--secret-stdin`	Yes	Yes	Read the client secret from standard input.
`--secret <str>`	Yes	Yes	Client secret. Prefer `--secret-stdin`. Asked if omitted.
`--title <str>`	Yes	Yes	Name displayed on the login button.
`--scopes <str>`	Yes		Scopes to request.
`--pkce` / `--no-pkce`	Yes		Use PKCE. Default `false`.
`--host <str>`	Yes		Host override.

After adding a provider, the CLI prints the callback URL to register at the identity provider, built from url. For OIDC it is https://<your-domain>/api/auth/sso/callback/<providerId>. For OAuth providers, check the expected URL in the OAuth2 setup page.

A provider ID must be unique: adding an existing one fails — remove it first.

`dashboard auth list`

Lists the configured providers: kind, ID, title, issuer (or provider name) and callback URL.

portabase dashboard auth list <DASHBOARD_PATH>

`dashboard auth remove`

Removes a provider and all its AUTH_OIDC_<ID>_* / AUTH_SOCIAL_<ID>_* variables.

portabase dashboard auth remove [OPTIONS] <DASHBOARD_PATH> [PROVIDER_ID]

-y, --yes skips the confirmation. Without PROVIDER_ID, an interactive menu is shown.

Removing the last provider while password_auth is false is refused. Re-enable password login first: portabase dashboard set <PATH> password_auth true.