Migration guide

This page covers the changes that can break an installation or a script when upgrading from the CLI 26.08.12 or earlier. The old commands are documented in Legacy CLI.

Renamed commands

The old forms fail. portabase db was removed: database commands only apply to an agent, so they live under portabase agent db.

docker-compose.yml is generated

The CLI rebuilds docker-compose.yml from .env and databases.json every time the configuration changes (set, unset, db add, db remove, auth add, auth remove, build).

• Put your customisations in docker-compose.override.yml. Docker Compose merges it and the CLI never touches it.
• The first time, the old file is saved as docker-compose.legacy.yml.
• Service and volume names do not change: your data is kept.

Scripts

• Without a terminal (CI, pipes, cron), the CLI never prompts. Pass every value as a flag, and secrets with --key-stdin, --password-stdin, etc.
• Confirmations that default to no are refused in that mode: add --force or --yes.
• Exit codes changed: 2 for invalid input, 3 configuration, 4 Docker, 130 canceled. See Exit codes.

printf '%s\n' "$EDGE_KEY" | portabase agent create my-agent --key-stdin --tz UTC --yes

Other changes

• agent db remove asks for confirmation (--yes to skip) and accepts --id.
• restart also creates containers added since the last start.
• Templates ship with the CLI: no internet access needed to create a component.
• update verifies the binary checksum.

Upgrade steps

tar czf my-agent-backup.tgz my-agent/

portabase update

portabase build ./my-agent --diff

portabase build ./my-agent
portabase restart ./my-agent