# CLI Command Reference > Every watasu CLI command, in one searchable page. This page lists every `watasu` command, grouped by namespace. Run any command with `--help` for full flag details. Most commands accept `--app ` (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 ` | Log in with an API key (CI/automation). | | `watasu logout` | Remove local credentials. | | `watasu whoami` | Show the currently logged-in user. | | `watasu token` | Print the stored API token, for scripting (e.g. `sshpass -p "$(watasu token)" ...`). | | `watasu ssh [command...]` | Open an [SSH sandbox session](https://docs.watasu.io/sandboxes/ssh.md); handles the token prompt automatically. `--team ` selects a team. | | `watasu --version` | Show the CLI version. | | `watasu --help` | Show flags for a specific command. | ## Apps | Command | What it does | | ------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `watasu apps` | List your apps. `--all` includes all teams, `--team ` filters to one. | | `watasu create ` | Create a new app and add a `watasu` Git remote. | | `watasu create --team ` | Create the app in a team. | | `watasu create --region ` | Create the app in a specific [region](https://docs.watasu.io/reference/regions.md). | | `watasu create --addons ` | Create an app and provision add-ons in one call (comma-separated `service` or `service:plan`). | | `watasu create --no-remote` | Create without adding a local Git remote. | | `watasu apps:rename --app ` | Rename an app. Updates the managed URL and Git remote. | | `watasu apps:destroy --app --confirm ` | Destroy an app. Requires confirmation by re-typing the name. | | `watasu git:remote --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 ` | List team members. `--pending` shows open invitations, `--role ` filters. | | `watasu members:add --team --role ` | Invite a user as `admin`, `member`, or `viewer`. | | `watasu members:set --team --role ` | Change a member's role. | | `watasu members:remove --team ` | Remove a member from the team. | | `watasu access --app ` | List who has access to an app. | | `watasu access:add --app --permissions ` | Grant app access (`deploy`, `manage`, `operate`, `view`, comma-separated). | | `watasu access:update --app --permissions ` | Change a collaborator's permissions. | | `watasu access:remove --app ` | Remove a collaborator. | | `watasu apps:join --app ` | Add yourself to a team app. | | `watasu apps:leave --app ` | Remove yourself from a team app. | | `watasu apps:lock --app ` | Prevent team members from self-joining the app. | | `watasu apps:unlock --app ` | Allow any team member to join again. | ## Config vars | Command | What it does | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `watasu config --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 ` | Set one or more config vars. Preserves existing secret/plain state. | | `watasu config:set KEY=value --secret --app ` | Set vars and mark them as secret. | | `watasu config:set KEY=value --plain --app ` | Set vars as plain (visible) config. | | `watasu config:set --file .env --app ` | Bulk-import vars from a dotenv file. Combine with `--secret` to import them as secrets. | | `watasu config:unset KEY [KEY ...] --app ` | Remove config vars. | Every change to config vars triggers a new release. ## Processes and scaling | Command | What it does | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `watasu pods --app ` | Show the formation: process types, replica counts, pod sizes, routing. Alias: `watasu ps`. | | `watasu pods:scale web=2 worker=1 --app ` | Scale replica counts per process type. | | `watasu pods:type web=standard-2x --app ` | Change [pod sizes](https://docs.watasu.io/reference/pod-sizes.md) per process type. | | `watasu apps:trust , --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 ` | Show recent log lines (default 20 per instance). | | `watasu logs --tail --app ` | Stream logs continuously. | | `watasu logs --num 100 --app ` | Fetch more history per instance. | | `watasu logs --process-type web --app ` | Filter to one process type. | | `watasu logs --dyno-name --app ` | Filter to a single instance. | For persistent, searchable logs, attach the [Logs add-on](https://docs.watasu.io/observability/logs.md). ## Domains | Command | What it does | | ------------------------------------------------------------ | ----------------------------------------------------------- | | `watasu domains --app ` | List domains attached to an app. | | `watasu domains:add --app ` | Attach a custom domain. Returns the DNS target to point at. | | `watasu domains:add --process --app ` | Attach to a specific public web process. | | `watasu domains:add --wait --app ` | Attach and block until the domain becomes active. | | `watasu domains:info --app ` | Show a domain's status, target, and attached process. | | `watasu domains:wait --app ` | Block until DNS verifies and TLS is provisioned. | | `watasu domains:remove --app ` | Detach a domain. | ## Add-ons (general) | Command | What it does | | ------------------------------------------------------------------------ | ---------------------------------------------------------------- | | `watasu addons --app ` | List add-ons attached to an app. | | `watasu addons:create [:] --app ` | Provision an add-on and attach it, e.g. `postgresql:standard-0`. | | `watasu addons:create postgresql --postgres-version --app ` | Choose the PostgreSQL major version at provision time. | | `watasu addons:attach --app ` | Attach an existing add-on to another app. | | `watasu addons:attach --app --as ` | Attach with an alias. Exported env vars get the alias prefix. | | `watasu addons:detach --app ` | Detach an add-on from an app (does not destroy it). | | `watasu addons:info ` | Show plan, status, connection details. | | `watasu addons:wait ` | Block until the add-on is ready. | | `watasu addons:destroy ` | Destroy an add-on. Destructive. | ## Add-on backups | Command | What it does | | --------------------------------------------- | ---------------------------------------------------------- | | `watasu addons:backups ` | List backups for an add-on. | | `watasu addons:backups:capture ` | Capture a manual backup. | | `watasu addons:restore ` | Restore a backup into a new replacement add-on. | | `watasu addons:restore --file ` | Upload a local backup file and restore from it. | | `watasu addons:promote ` | Promote a restored add-on into the original's attachments. | See [Backups and Restores](https://docs.watasu.io/workflows/backups-and-restores.md) for the full workflow and which services support backups. ## PostgreSQL | Command | What it does | | ------------------------------------------------------------------------ | ------------------------------------------------------------ | | `watasu pg --app ` | Show database info (alias for `pg:info`). | | `watasu pg:psql DATABASE_URL --app ` | Open an interactive `psql` session. | | `watasu pg:wait --app ` | Block until databases are available. | | `watasu pg:follow DATABASE_URL --app --name --plan ` | Create a follower (read replica). | | `watasu pg:backups --app ` | List PostgreSQL backups. | | `watasu pg:backups:capture --app ` | Capture a manual backup. | | `watasu pg:backups:restore DATABASE_URL --app ` | Restore into a replacement database. | | `watasu pg:promote --app ` | Promote a restored database into the original's attachments. | ## Valkey and ClickHouse | Command | What it does | | ----------------------------------- | --------------------------------------- | | `watasu valkey:cli --app ` | Open an interactive Valkey session. | | `watasu redis:cli --app ` | Compatibility alias for `valkey:cli`. | | `watasu clickhouse:cli --app ` | Open an interactive ClickHouse session. | ## Common patterns ### Targeting apps Most commands accept `--app `. 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](https://docs.watasu.io/cli/authentication.md#how-the-cli-chooses-an-app). ### Plan slugs Where commands take a plan, the format is `:`: ```bash 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](https://docs.watasu.io/reference/addon-plans.md). ### Aliasing add-ons When an app has more than one of the same service: ```bash 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: ```bash 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: ```bash watasu pg:psql reporting --app my-app ``` ## Maintenance mode ```bash watasu maintenance on --app my-app watasu maintenance status --app my-app watasu maintenance off --app my-app ``` Shows a maintenance page on public app domains while workers keep running. Supports `--json`, `--no-wait`, and `--timeout`. See [maintenance mode](https://docs.watasu.io/apps/maintenance.md). [View this page on the web](https://docs.watasu.io/cli/reference/)