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.
pywa login
Section titled “pywa login”pywa login # opens a device-code flowpywa 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.
pywa logout
Section titled “pywa logout”Forgets the stored login. (equivalent to pywa cloud logout)
pywa whoami
Section titled “pywa whoami”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.
pywa cloud bots create <name> [--entrypoint-override <module:var>] [--bot-directory <path>]pywa cloud bots listpywa 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.
Environment variables & secrets
Section titled “Environment variables & secrets”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.
Scaffolding a project
Section titled “Scaffolding a project”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:
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.
Linking a directory
Section titled “Linking a directory”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.
Deploying
Section titled “Deploying”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.
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.
Managing a running bot
Section titled “Managing a running bot”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.
Connecting WhatsApp
Section titled “Connecting WhatsApp”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.
Database integrations
Section titled “Database integrations”Connecting a provider to your team and linking a database to a bot are done in the dashboard. See Database Integrations.
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.
Local development
Section titled “Local development”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.
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.
Environments
Section titled “Environments”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.
Deploy tokens (CI)
Section titled “Deploy tokens (CI)”pywa cloud deploy-tokens create <name> [--expires-in-days <n>] [--bot <bot-id>] # n: 1-365, default 90pywa 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:
export PYWA_CLOUD_TOKEN=<the deploy token>export PYWA_CLOUD_BOT_ID=<bot-id>pywa deployThis bypasses your stored personal login completely — nothing CI runs ever touches it. --bot on
deploy itself works too, instead of PYWA_CLOUD_BOT_ID.
CI setup
Section titled “CI setup”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.
Not built yet
Section titled “Not built yet”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.