CLI Reference
Master the Portabase command-line tool.
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.
Installation
curl -sL https://portabase.io/install | bashCheck the installed version:
portabase --versionComponent 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 |
|---|---|---|
--key <str> | -k | The Edge Key provided by the Dashboard. If omitted, it will be requested interactively. |
--start | -s | Start the agent immediately after creation. |
Interactive Assistant
If you simply run portabase agent my-agent, the CLI will launch an assistant to:
- Request the key.
- Offer to automatically add database containers (Postgres/MariaDB).
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 |
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>).
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:
- Type: PostgreSQL, MySQL, MariaDB.
- 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>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. Useful after a configuration change (db add or modification in .env).
portabase restart <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.