CLI Command Reference

This page lists every watasu command, grouped by namespace. Run any command with --help for full flag details. Most commands accept --app <name> (or infer the app from the watasu Git remote) and --json for machine-readable output.

Global

Command	What it does
watasu login	Browser login. Stores credentials locally for API and Git.
watasu login --api-key <key>	Log in with an API key (CI/automation).
watasu logout	Remove local credentials.
watasu whoami	Show the currently logged-in user.
watasu --version	Show the CLI version.
watasu <command> --help	Show flags for a specific command.

Apps

Command	What it does
watasu apps	List your apps. --all includes all teams, --team <team> filters to one.
watasu create <name>	Create a new app and add a watasu Git remote.
watasu create <name> --team <team>	Create the app in a team.
watasu create <name> --region <region>	Create the app in a specific region.
watasu create <name> --addons <list>	Create an app and provision add-ons in one call (comma-separated service or service:plan).
watasu create <name> --no-remote	Create without adding a local Git remote.
watasu apps:rename <new-name> --app <app>	Rename an app. Updates the managed URL and Git remote.
watasu apps:destroy --app <app> --confirm <app>	Destroy an app. Requires confirmation by re-typing the name.
watasu git:remote --app <app>	Add or update the watasu Git remote in the current repo.

Teams and access

Command	What it does
watasu teams	List teams you belong to.
watasu members --team <team>	List team members. --pending shows open invitations, --role <role> filters.
watasu members:add <email> --team <team> --role <role>	Invite a user as admin, member, or viewer.
watasu members:set <email> --team <team> --role <role>	Change a member’s role.
watasu members:remove <email> --team <team>	Remove a member from the team.
watasu access --app <app>	List who has access to an app.
watasu access:add <email> --app <app> --permissions <list>	Grant app access (deploy, manage, operate, view, comma-separated).
watasu access:update <email> --app <app> --permissions <list>	Change a collaborator’s permissions.
watasu access:remove <email> --app <app>	Remove a collaborator.
watasu apps:join --app <app>	Add yourself to a team app.
watasu apps:leave --app <app>	Remove yourself from a team app.
watasu apps:lock --app <app>	Prevent team members from self-joining the app.
watasu apps:unlock --app <app>	Allow any team member to join again.

Config vars

Command	What it does
watasu config --app <app>	Show effective config for an app (includes add-on-injected vars). Secret values are redacted in output.
watasu config:set KEY=value [KEY=value ...] --app <app>	Set one or more config vars. Preserves existing secret/plain state.
watasu config:set KEY=value --secret --app <app>	Set vars and mark them as secret.
watasu config:set KEY=value --plain --app <app>	Set vars as plain (visible) config.
watasu config:set --file .env --app <app>	Bulk-import vars from a dotenv file. Combine with --secret to import them as secrets.
watasu config:unset KEY [KEY ...] --app <app>	Remove config vars.

Every change to config vars triggers a new release.

Processes and scaling

Command	What it does
watasu pods --app <app>	Show the formation: process types, replica counts, pod sizes, routing. Alias: watasu ps.
watasu pods:scale web=2 worker=1 --app <app>	Scale replica counts per process type.
watasu pods:type web=standard-2x --app <app>	Change pod sizes per process type.
watasu apps:trust <app1>,<app2> --app <app>	Allow listed sibling apps to reach this app’s internal *-tcp services. Run without arguments to show the current list, --clear to reset it.

Logs

Command	What it does
watasu logs --app <app>	Show recent log lines (default 20 per instance).
watasu logs --tail --app <app>	Stream logs continuously.
watasu logs --num 100 --app <app>	Fetch more history per instance.
watasu logs --process-type web --app <app>	Filter to one process type.
watasu logs --dyno-name <instance> --app <app>	Filter to a single instance.

For persistent, searchable logs, attach the Logs add-on.

Domains

Command	What it does
watasu domains --app <app>	List domains attached to an app.
watasu domains:add <hostname> --app <app>	Attach a custom domain. Returns the DNS target to point at.
watasu domains:add <hostname> --process <name> --app <app>	Attach to a specific public web process.
watasu domains:add <hostname> --wait --app <app>	Attach and block until the domain becomes active.
watasu domains:info <hostname> --app <app>	Show a domain’s status, target, and attached process.
watasu domains:wait <hostname> --app <app>	Block until DNS verifies and TLS is provisioned.
watasu domains:remove <hostname> --app <app>	Detach a domain.

Add-ons (general)

Command	What it does
watasu addons --app <app>	List add-ons attached to an app.
watasu addons:create <service>[:<plan>] --app <app>	Provision an add-on and attach it, e.g. postgresql:standard-0.
watasu addons:create postgresql --postgres-version <major> --app <app>	Choose the PostgreSQL major version at provision time.
watasu addons:attach <addon> --app <app>	Attach an existing add-on to another app.
watasu addons:attach <addon> --app <app> --as <ALIAS>	Attach with an alias. Exported env vars get the alias prefix.
watasu addons:detach <addon> --app <app>	Detach an add-on from an app (does not destroy it).
watasu addons:info <addon>	Show plan, status, connection details.
watasu addons:wait <addon>	Block until the add-on is ready.
watasu addons:destroy <addon>	Destroy an add-on. Destructive.

Add-on backups

Command	What it does
watasu addons:backups <addon>	List backups for an add-on.
watasu addons:backups:capture <addon>	Capture a manual backup.
watasu addons:restore <addon> <backup-id>	Restore a backup into a new replacement add-on.
watasu addons:restore <addon> --file <path>	Upload a local backup file and restore from it.
watasu addons:promote <addon>	Promote a restored add-on into the original’s attachments.

See Backups and Restores for the full workflow and which services support backups.

PostgreSQL

Command	What it does
watasu pg --app <app>	Show database info (alias for pg:info).
watasu pg:psql DATABASE_URL --app <app>	Open an interactive psql session.
watasu pg:wait --app <app>	Block until databases are available.
watasu pg:follow DATABASE_URL --app <app> --name <new> --plan <plan>	Create a follower (read replica).
watasu pg:backups --app <app>	List PostgreSQL backups.
watasu pg:backups:capture --app <app>	Capture a manual backup.
watasu pg:backups:restore <backup-id-or-file> DATABASE_URL --app <app>	Restore into a replacement database.
watasu pg:promote <database> --app <app>	Promote a restored database into the original’s attachments.

Valkey and ClickHouse

Command	What it does
watasu valkey:cli --app <app>	Open an interactive Valkey session.
watasu redis:cli --app <app>	Compatibility alias for valkey:cli.
watasu clickhouse:cli --app <app>	Open an interactive ClickHouse session.

Common patterns

Targeting apps

Most commands accept --app <name>. Inside a Git repo with the watasu remote, you can usually omit it. For scripts and CI, always pass --app explicitly. See Authentication → How the CLI chooses an app.

Plan slugs

Where commands take a plan, the format is <service>:<plan>:

watasu addons:create postgresql:standard-0 --app my-app
watasu addons:create valkey:hobby-1 --app my-app

The full plan catalog is in Add-on Plans.

Aliasing add-ons

When an app has more than one of the same service:

watasu addons:attach reporting-db --app my-app --as REPORTING

The alias prefixes the exported env vars (e.g. REPORTING_DATABASE_URL).

Database identifiers

PostgreSQL and CLI-session commands take the env var name (not the URL itself) to identify which add-on to operate on:

watasu pg:psql DATABASE_URL --app my-app
watasu pg:psql REPORTING_DATABASE_URL --app my-app

This works whether the var came from the default attachment (DATABASE_URL) or an alias (REPORTING_DATABASE_URL). The attachment alias on its own works too:

watasu pg:psql reporting --app my-app