Skip to content
Pywa Cloud is not live yet - there is no running control plane or dashboard to sign up on, and the CLI package is not published. Everything on this site describes a real, working, tested system, not a roadmap - but none of it is something you can actually run against Pywa Cloud today, and commands/flags/behavior can still change before it is.

CLI Reference

pip install pywa-cloud-cli gives you every command below, reached as pywa cloud <command> — installing it pulls in pywa itself too, and pywa’s own CLI automatically mounts pywa cloud ... on top of it. A handful of the most common commands also get a top-level shortcut directly on pywa, shown below wherever one exists: pywa login, pywa logout, pywa whoami, pywa deploy.

Run pywa cloud --help or pywa cloud <command> --help (or, for a shortcut, pywa <command> --help) for the exact same information this page describes, straight from the CLI itself.

Terminal window
pywa login # opens a device-code flow
pywa login --token <token> # CI / scripted login

(equivalent to pywa cloud login)

With no --token, login starts a real device-code flow: it prints a short code and opens a confirmation page in your browser, where you sign in and approve it; the CLI polls until you do, or the code expires after 10 minutes. --token <token> skips all of that and logs in directly with an existing token — the CI path, and also how a deploy token is normally used.

No account yet? Sign up at dashboard.pywa.cloud — that’s also where you’d be sent by the device-code link above if you’re not already signed in.

Either way, the resulting token is stored at an OS-standard config location — never in your project directory, so it can’t end up committed by accident:

  • macOS: ~/Library/Application Support/pywa-cloud/auth.json
  • Linux: $XDG_CONFIG_HOME/pywa-cloud/auth.json (default ~/.config/...)
  • Windows: %APPDATA%\pywa-cloud\auth.json

Once you’ve logged in, every other command in this reference just works. $PYWA_CLOUD_CLI_CONFIG_DIR overrides the config location entirely, useful for running more than one isolated login on one machine.

Forgets the stored login. (equivalent to pywa cloud logout)

Shows the identity the current login resolves to, and which API it’s pointed at. (equivalent to pywa cloud whoami)

Commands that act on one bot use the bot linked to the current project (.pywacloud/link.json, written by pywa deploy or pywa cloud link). Pass --bot <bot-id> to target another one, or set PYWA_CLOUD_BOT_ID.

Terminal window
pywa cloud bots create <name> [--entrypoint-override <module:var>] [--bot-directory <path>]
pywa cloud bots list
pywa cloud bots get [<bot-id>]
pywa cloud bots delete [<bot-id>] [--yes]
pywa cloud bots set-entrypoint [<module:var>] [--bot <bot-id>]
pywa cloud bots set-directory [<path>] [--bot <bot-id>]

<name> is only a display name; a bot is identified by its id. Deleting a bot also stops it, if it’s currently running. set-entrypoint sets or (called with no module:var) clears the bot’s entrypoint override — see Deploying a Pywa Bot for when you’d need one. set-directory sets or (called with no path) clears the bot’s application directory, for deploying one member of a monorepo — see the same guide’s “Working in a monorepo” section.

Terminal window
pywa cloud env set <key> [<value>] [--secret] [--bot <bot-id>]
pywa cloud env get <key> [--bot <bot-id>]
pywa cloud env list [--bot <bot-id>]
pywa cloud env delete <key> [--bot <bot-id>]

See Environment Variables & Secrets for the full semantics — set is create-or-update, and --secret is fixed at creation.

There’s no scaffolding command in pywa-cloud-cli itself — use pywa’s own project generator, with --cloud so the result is deployable as-is:

Terminal window
pywa new --cloud [--async] [-o <directory>]

This writes main.py (credentials read from PYWA_PHONE_ID/PYWA_TOKEN, no hardcoded values, no local tunnel setup) plus a real pyproject.toml and .gitignore — ready for pywa deploy as-is. Plain pywa new (no --cloud) is pywa’s own default scaffold instead: meant for editing and running locally, not deploying as-is. See pywa new --help (or pywa’s own docs) for the full set of options. Deploying a Pywa Bot covers what a project needs to be deployable if you’d rather write one from scratch or adapt an existing project.

Terminal window
pywa cloud link <bot-id> [path]
pywa cloud unlink [path]

path defaults to the current directory. See Deploying a Pywa Bot for how this interacts with deploy.

Terminal window
pywa deploy [path] [--bot <bot-id>]

(equivalent to pywa cloud deploy)

A directory’s first deploy asks which bot this is (Enter picks the bot named like the directory, or creates a new one; pass --bot to skip the prompt — required in CI, where there’s no terminal to ask); later deploys in the same directory reuse the link automatically. In a terminal, deploy also does what the deploy needs: if the bot has no WhatsApp number it runs the connect steps first (CI fails at once instead, before uploading), and it offers to set the variables from a local .env that the bot doesn’t have yet. It refuses an upload over the 50 MB limit and lists the biggest files. See Deploying a Pywa Bot for what actually happens and what’s excluded from the upload.

Terminal window
pywa cloud deployments list [--bot <bot-id>]
pywa cloud deployments get <deployment-id> [--bot <bot-id>]
pywa cloud deployments log <deployment-id> [--bot <bot-id>]
pywa cloud deployments rollback <deployment-id> [--bot <bot-id>]

deployments list shows past deployments for a bot (status, Python version, timestamp). deployments get fetches full metadata for a specific deployment attempt. deployments rollback re-runs a previous successful deployment’s already-built version directly — no re-upload, no rebuild — using the bot’s current env vars (so a secret rotated since then still applies), and records a new deployment rather than mutating the old one. Requires the Admin/Owner team role. deployments log (alias logs) shows that deployment’s deploy log: one line per step, plus your bot’s own output if it failed to start.

Terminal window
pywa cloud status [--bot <bot-id>]
pywa cloud stop [--bot <bot-id>]
pywa cloud start [--bot <bot-id>]
pywa cloud restart [--bot <bot-id>]

See Managing a Running Bot for what each one actually does, and what’s automatic versus what needs you to act.

status also makes a real request into a running bot (an unauthenticated GET, expecting pywa’s own webhook challenge handler to answer 403) and prints whether it is serving — stronger proof of life than whether the process exists. Live CPU/memory usage, your plan’s limits and request stats are in the dashboard.

Terminal window
pywa cloud connect [--bot <bot-id>]
pywa cloud connect-status [--bot <bot-id>]

See Connecting a WhatsApp Number. A WABA connection is a team-level resource, shared across every bot on the team — connect is the interactive entry point: it reuses a team’s Meta Embedded Signup connection (or starts one), then assigns one of its phone numbers to the given bot, asking only when there is a real choice (a lone WABA or a lone number is used as is); the Embedded Signup link itself is single-use and expires after 15 minutes. connect-status shows whether (and to which WABA/phone) the bot is currently connected, including a warning if Meta has since flagged the underlying WABA as disconnected/restricted/banned. Assigning or clearing a number by id, connecting a WABA with your own Meta App token, and retrying a webhook that Meta refused are done in the dashboard.

Connecting a provider to your team and linking a database to a bot are done in the dashboard. See Database Integrations.

Terminal window
pywa cloud logs [--bot <bot-id>] [--tail <n>] [--since <timestamp>] [--follow] [--interval <seconds>]

See Logs. --tail defaults to 200 lines; --since (RFC3339, e.g. 2024-01-01T00:00:00Z) is a one-shot filter and is ignored together with --tail when combined with --follow, which manages its own cursor; --follow polls every --interval seconds (default 2.0) until Ctrl+C.

Terminal window
pywa dev --tunnel [--bot <bot-id>]

The usual way to develop against real Meta webhooks: pywa dev (pywa’s own local dev server) with --tunnel also relays this bot’s inbound webhook traffic here instead of to its deployed version, so you don’t need a separate tunnel tool or a repointed callback URL. --bot picks which Pywa Cloud bot to relay from (defaults to the current directory’s linked bot). --tunnel also fetches this bot’s real, live PYWA_TOKEN/PYWA_PHONE_ID/PYWA_WABA_ID and injects them into your local process’s environment first, unconditionally — overwriting anything your project’s own .env/hardcoded values set for those same three names — since relaying real webhooks to a process that can’t send replies isn’t a useful state to be in. Your bot’s pywa cloud env variables and secrets are injected too, but never over a value you already set locally. See Local Development for the full story.

Terminal window
pywa cloud tunnel [--host <host>] [--port <local-port>] [--bot <bot-id>]

The same relay as a standalone, foreground command — for pairing with anything other than pywa dev (a different framework runner, a manual process, etc.). --host (default 127.0.0.1) and --port (default 8000) are the address your own bot process is bound to. Opt-in and explicit either way: only active while the command is running; Ctrl+C (or any disconnect) hands traffic straight back to the deployed version. A dropped connection (network blip, sleep, a Pywa Cloud restart) is retried with backoff while the command runs; being replaced by a teammate’s tunnel, stopped from the dashboard, or not being an admin ends it. If your machine goes silent for 45 s, Pywa Cloud drops the tunnel and the deployed version gets webhooks again.

Terminal window
pywa cloud demote [--bot <bot-id>] [--yes]

A new bot is in development; only a development bot can be tunnelled (pywa dev --tunnel, pywa cloud tunnel) or have its credentials fetched for local use. Promoting it to production is done in the dashboard and ends a live tunnel. demote moves it back, asks for confirmation (--yes skips it) and is recorded in the audit log. Both need the admin role. Bots that existed before environments were introduced are in production.

Terminal window
pywa cloud deploy-tokens create <name> [--expires-in-days <n>] [--bot <bot-id>] # n: 1-365, default 90
pywa cloud deploy-tokens list [--bot <bot-id>]
pywa cloud deploy-tokens delete <token-id> [--bot <bot-id>]
pywa cloud deploy-tokens regenerate <token-id> [--expires-in-days <n>] [--bot <bot-id>]

A deploy token is scoped to exactly one bot and can only be used for deploy — nothing else. The token value is shown once, at creation (or regeneration), and never again; losing it means regenerate, not looking it up. You can also manage tokens in the dashboard, under the bot’s Deploy tokens tab (team admins and owners only). For CI, skip pywa login entirely:

Terminal window
export PYWA_CLOUD_TOKEN=<the deploy token>
export PYWA_CLOUD_BOT_ID=<bot-id>
pywa deploy

This bypasses your stored personal login completely — nothing CI runs ever touches it. --bot on deploy itself works too, instead of PYWA_CLOUD_BOT_ID.

Terminal window
pywa cloud setup-ci [--bot <bot-id>] [--branch <name>] [--force]

Scaffolds .github/workflows/deploy.yml in the current project, wiring up the deploy-token flow above as an automated on-push deploy. Reads repository secrets PYWA_CLOUD_TOKEN and PYWA_CLOUD_BOT_ID — add these under your repo’s Settings → Secrets before the workflow can run. --branch defaults to whatever branch your project’s own git checkout is currently on; --force overwrites an existing workflow file. The generated workflow installs both pywa and pywa-cloud-cli (pywa alone doesn’t pull the cloud package in) and runs pywa cloud deploy.

Billing/usage metering — a business decision that hasn’t been made yet, not just an unbuilt command. Teams, roles, and invites are fully implemented (see Accounts, Teams & Permissions) but don’t have CLI commands of their own yet, since day-to-day account use rarely needs them — pywa login/logout/whoami above already cover the everyday auth surface. Pointing a WhatsApp Flow at a bot is also dashboard-only for now — there’s no pywa cloud flows ... yet.

Almost everything above also has a dashboard equivalent — deploying, env vars, logs, lifecycle (status/stop/start/restart/health), connecting WhatsApp, database integrations. The CLI isn’t the only way to run Pywa Cloud, just the scriptable one; each guide linked from here says explicitly where the dashboard can or can’t do the same thing.