CLI reference (Legacy)
Command reference of the Portabase CLI up to version 26.08.12.
Legacy documentation
This page documents the Portabase CLI 26.08.12 and earlier. For newer versions, see the current reference and the migration guide.
The Portabase CLI is the central orchestration tool. It acts as an intelligent wrapper on top of Docker Compose to:
- Generate valid and secure configurations.
- Manage the container lifecycle (start/stop/logs).
- Administer database connections without manually editing JSON files.
In these versions, compose templates are downloaded from the Portabase servers when a component is created (internet access required), and the generated docker-compose.yml can be edited by hand.
Component Initialization
These commands generate the folder structure, docker-compose.yml files, .env configurations, and security keys.
agent
Creates a new backup agent. The agent is the connector that installs on your database servers.
portabase agent [OPTIONS] NAMEArguments
| Argument | Required | Description |
|---|---|---|
NAME | Yes | The name of the folder to create (e.g., prod-db-01). |
Options
| Option | Alias | Description | Default |
|---|---|---|---|
--key <str> | -k | The Edge Key provided by the Dashboard. If omitted, it will be requested interactively. | None |
--tz <str> | Timezone for the agent. Asked interactively when left to UTC. | UTC | |
--polling <int> | Polling frequency in seconds. Asked interactively when left to 5. | 5 | |
--start | -s | Start the agent immediately after creation. | False |
Interactive Assistant
If you simply run portabase agent my-agent, the CLI will launch an assistant to:
- Request the key, the timezone and the polling frequency.
- Ask whether to add an
extra_hostsmapping (localhost:host-gateway). - Loop on "What do you want to configure?" (
database,docker-volumeordone) to add new database containers or existing databases. - Show the proposed configuration and ask for confirmation before writing the files.
dashboard
Creates a Dashboard instance (the web management interface).
portabase dashboard [OPTIONS] NAMEOptions
| Option | Alias | Description | Default |
|---|---|---|---|
--port <int> | The web listening port for the interface. | 8887 | |
--start | -s | Start the dashboard immediately after creation. | False |
The assistant asks for the database setup: external (dedicated PostgreSQL container, recommended), internal (embedded database) or custom (credentials of an existing PostgreSQL).
Database Management (db)
The db module allows you to modify an agent's databases.json configuration without risk of syntax errors.
These commands modify the configuration. For them to take effect, you must restart the agent (portabase restart <AGENT_PATH>).
db list
Displays a summary table of databases configured for a given agent.
portabase db list <AGENT_PATH>db add
Launches an interactive assistant to add a new connection to the configuration.
portabase db add <AGENT_PATH>The assistant will ask you for:
- What to configure: a
databaseor adocker-volume. - Mode:
new(a container added to the agent'sdocker-compose.yml) orexisting. - Type:
postgresql,postgresql-cluster,mysql,mariadb,sqlite,firebird,mongodb,redis,valkey,mssql. - Host: The IP address or hostname (use
localhostfor a DB on the same server). - Port: The listening port (e.g., 5432).
- Credentials: Username and password.
db remove
Removes a database from the configuration via an interactive selection menu.
portabase db remove <AGENT_PATH>Only the entry in databases.json is removed. A container created with db add stays in docker-compose.yml, with its variables in .env and its data volume.
Lifecycle (Operations)
These commands replace direct use of docker compose. They must target the folder of a component (Agent or Dashboard).
Productivity tip
If you are already in the component folder, you can use . as the path. Example: portabase logs .
start
Starts containers in detached mode (background). Equivalent to docker compose up -d.
portabase start <PATH>stop
Stops containers cleanly.
portabase stop <PATH>restart
Restarts all services (docker compose restart). Useful after a configuration change (db add or modification in .env).
portabase restart <PATH>docker compose restart does not create containers added since the last start. After db add with a new container, run portabase start <PATH>.
logs
Displays container logs.
portabase logs [OPTIONS] <PATH>Options
| Option | Alias | Description |
|---|---|---|
--follow / --no-follow | -f | Follows logs in real time (enabled by default). Press Ctrl+C to exit. |
uninstall
Removes the entire deployment.
portabase uninstall [OPTIONS] <PATH>Options
| Option | Alias | Description |
|---|---|---|
--force | -f | Does not ask for confirmation before deleting. |
This command performs a docker compose down -v. This removes containers AND data volumes (local databases, configurations).
This action is irreversible.
Backup Decryption (decrypt)
Decrypts Portabase .enc backup files (AES-256-GCM) and restores the original archive. Works on a single file or on a whole folder of .enc files.
portabase decrypt [OPTIONS] INPUT_PATH [OUTPUT_PATH]Arguments
| Argument | Required | Description |
|---|---|---|
INPUT_PATH | Yes | A .enc file, or a folder containing .enc files (top level; all are decrypted). |
OUTPUT_PATH | No | Output file or folder, matching the input type. Defaults to the input's directory. |
Options
| Option | Alias | Description | Default |
|---|---|---|---|
--key <path> | -k | Path to the master key file (raw 32-byte or Base64 AES-256 key). | ./master_key.bin |
Decrypt a single file:
portabase decrypt backup.tar.gz.enc backup.tar.gz --key master_key.binDecrypt every .enc in a folder into another folder:
portabase decrypt ./backups ./restored --key master_key.binOmit the output to write next to the input, and omit --key to use master_key.bin from the current directory:
portabase decrypt backup.tar.gz.encMaster key
The master key is the same 32-byte AES-256 key used for encryption. Download it from the dashboard in Settings, Storage section. When --key is not provided, the CLI looks for master_key.bin in the current directory.
Folder mode is resilient
When decrypting a folder, each file is handled independently: one corrupt or wrong-key file does not stop the batch. A summary lists which files succeeded and which failed (with the reason), and the command exits with a non-zero code if any failed.
Large backups
Decryption is fully streaming: files are processed chunk by chunk, so memory stays bounded (tens of MB) even for multi-gigabyte (>2 GB) backups. The output is written atomically, so a failure never leaves a partial file behind.
Maintenance and Troubleshooting
Manage the global behavior and settings of the Portabase CLI.
config channel
Changes the update channel to switch between stable and beta versions.
portabase config channel <stable|beta>config show
Displays the current CLI configuration, including the active update channel.
portabase config showupdate
Updates the CLI to the latest available version. This command checks for updates on the official repository and applies security patches or new features.
portabase updateCommon Troubleshooting
Last updated on