Connections can also be managed from the interactive TUI (just run capsule with no arguments). Use the connection subcommands when you want to script or automate setup — e.g. provisioning a new server with Ansible, cloud-init, or a Docker entrypoint.
Subcommands
| Command | Description |
|---|
capsule connection add | Add a new database connection |
capsule connection list | List all configured connections |
capsule connection update | Update fields on an existing connection (e.g. rotate credentials) |
capsule connection remove | Remove a connection |
capsule connection add
capsule connection add --label <name> --type <postgres|mysql|mongo> [flags]
Flags
| Flag | Description |
|---|
--label, -l | Connection label (required) |
--type, -t | Database type: postgres, mysql, or mongo (required) |
--host | Database host (required for postgres/mysql) |
--port | Database port (defaults to 5432 for postgres, 3306 for mysql) |
--database, -d | Database name (required for postgres/mysql) |
--user, -u | Database user (required for postgres/mysql) |
--uri | Full MongoDB connection URI (mongo only) |
--docker | Docker container name — omit for a native (non-containerized) database |
Postgres / MySQL example
capsule connection add -l prod-postgres -t postgres \
--host db.example.com --port 5432 -d myapp -u admin
Enter database password (input hidden):
Connection added: prod-postgres (postgres)
MongoDB example
capsule connection add -l prod-mongo -t mongo
--uri isn’t passed, you’ll be prompted for the full connection string with input hidden (it contains embedded credentials):
Enter MongoDB connection URI (input hidden):
Connection added: prod-mongo (mongo)
For fully non-interactive setups (provisioning scripts, CI), set CAPSULE_CONN_PASSWORD or CAPSULE_CONN_URI as environment variables instead of being prompted. Neither is ever written to shell history since they’re read from the environment, not a flag.
capsule connection list
Lists all configured connections along with your plan’s connection usage.
2 / 3 connections
prod-postgres (postgres) db.example.com:5432/myapp
prod-mongo (mongo) mongodb+srv://cluster0.mongodb.net/myapp
capsule connection update
capsule connection update --connection <label> [flags]
remove + add when credentials rotate or a host changes, since remove deletes the associated schedule too.
Flags
| Flag | Description |
|---|
--connection, -c | Connection label to update (required) |
--host | New database host |
--port | New database port |
--database, -d | New database name |
--user, -u | New database user |
--uri | New full MongoDB connection URI (mongo only) |
--docker | New Docker container name |
--rotate-password | Prompt for a new password (input hidden) |
Rotating a password
capsule connection update --connection prod-postgres --rotate-password
Enter new database password (input hidden):
Connection updated: prod-postgres
CAPSULE_CONN_PASSWORD (or CAPSULE_CONN_URI for mongo) instead of passing --rotate-password — if either is set, the update applies it without any prompt:
CAPSULE_CONN_PASSWORD="$NEW_PASSWORD" capsule connection update --connection prod-postgres
Changing a host
capsule connection update --connection prod-postgres --host db-replica.example.com
capsule connection remove
capsule connection remove --connection <label>
capsule schedule for details on how that works.
This only removes the connection from Capsule — your actual database is never touched.
Notes
- Connections are stored locally in
~/.local/share/capsule/connections.json, encrypted at rest
- Every successful
add, update, and remove syncs to your dashboard automatically; a sync failure (e.g. offline) is logged as a warning but doesn’t block the local change
- Plan connection limits: Hobbyist = 1, Solo = 3, Pro = 5, Team = unlimited
See also
capsule schedule — schedule automatic backups for a connection you’ve addedcapsule doctor — verify the required database client tools are installed before adding a connection
