{
  "markdown": "# pingwa (client)\n\n[![PyPI](https://img.shields.io/pypi/v/pingwa.svg)](https://pypi.org/project/pingwa/)\n[![Python](https://img.shields.io/pypi/pyversions/pingwa.svg)](https://pypi.org/project/pingwa/)\n[![License: MIT](https://img.shields.io/pypi/l/pingwa.svg)](https://github.com/grzgrzgrz3/pingwa-client/blob/main/LICENSE)\n\nWhatsApp notifications for AI agents and scripts with **zero setup** — no Meta\naccount, no templates, no dashboard: text \"join\", get an API key,\n`curl → WhatsApp in 60s`. Two-way human-in-the-loop: your agent asks, you tap\na button to answer. From your terminal or an MCP client.\n\n<!-- mcp-name: io.github.grzgrzgrz3/pingwa -->\n\nThis is the **open-source (MIT) pingwa client**: a CLI, a tiny HTTP client, and an\nMCP server. It talks to a pingwa backend (the hosted service at\nhttps://pingwa.dev, or your own). The backend is separate and private;\nthis client is not.\n\n## Install & use\n\nNo install needed with [uv](https://docs.astral.sh/uv/):\n\n```bash\nexport PINGWA_KEY=pw_your_key          # get one: send \"join\" on WhatsApp to the service number\nuvx pingwa send \"build finished ✅\"     # notify your own phone\necho \"deploy done\" | uvx pingwa send -  # from stdin\nuvx pingwa ask \"Deploy to prod?\" --button yes --button no   # wait for a reply from your phone\nuvx pingwa replies                      # pull messages your phone sent back (out-of-band steering)\nuvx pingwa me                           # plan / quota / reply-window\nuvx pingwa keys                         # list active API keys (up to 10 named keys per number)\nuvx pingwa keys revoke ci               # revoke one by name (or reply 'revoke ci' on WhatsApp)\nuvx pingwa upgrade                      # get a Stripe link to go Pro (no password needed)\nuvx pingwa send \"x\" --json              # raw JSON response\n```\n\n**AI agents:** don't ask your human to copy-paste a key — drive the registration\nyourself (`POST /v1/registrations`; full recipe in\n[llms.txt](https://pingwa.dev/llms.txt)). The human only taps one WhatsApp link;\nthe key is claimed by you and never travels through the chat. Works for existing\naccounts too — it mints an additional named key.\n\nExit codes: `0` ok · `2` missing key · `3` quota exceeded · `1` other.\nOverride the backend with `PINGWA_BASE_URL` or `--base-url`.\n\n## Webhooks\n\nPrefer PUSH over polling `replies`? Register HTTPS endpoints and pingwa POSTs\nevery inbound WhatsApp message to them:\n\n```bash\nuvx pingwa webhooks                                   # list your webhooks\nuvx pingwa webhooks add https://your-host/pingwa-hook # returns a signing SECRET, shown ONCE\nuvx pingwa webhooks rm https://your-host/pingwa-hook  # by id, or by exact url\n```\n\n`add` prints a `whsec_...` secret **once** — store it now; it never appears\nagain. Each delivery carries an `X-Pingwa-Signature: sha256=<hex>` header (an\nHMAC-SHA256 of the raw body under that secret) — verify it and reject anything\nthat fails. Full verification recipe and payload shape:\n[llms.txt](https://pingwa.dev/llms.txt). Up to 5 active webhooks per account; to\nrotate a secret, `rm` then `add` again.\n\n## MCP server\n\nSame tools on stdio and remote: `notify(text)`, `ask(text, buttons?, timeout?)`,\n`check_replies(since?, wait?)`, `check_status()`, `upgrade()`.\n\nLocal (stdio) — for Claude Desktop / Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"pingwa\": {\n      \"command\": \"uvx\",\n      \"args\": [\"pingwa\", \"mcp\"],\n      \"env\": { \"PINGWA_KEY\": \"pw_your_key\" }\n    }\n  }\n}\n```\n\nRemote (Streamable HTTP, no install):\n\n```json\n{\n  \"mcpServers\": {\n    \"pingwa\": {\n      \"url\": \"https://pingwa.dev/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer pw_your_key\" }\n    }\n  }\n}\n```\n\nEvery error carries an `action` hint, so an agent knows what to do next.\n\n## What it sends\n\nOnly your message text and your key, to the pingwa backend you point it at — over\nHTTPS. Nothing else. The recipient is always your own phone (there is no \"to\"\nfield). See the service's [/privacy](https://pingwa.dev/privacy).\n\n## License\n\nMIT — see `LICENSE` in the repository root. It covers this client package only\n(`src/pingwa/client/`); the pingwa server is separate, private, and not\npublished. See `NOTICE` for the exact boundary.\n",
  "bytes": 4185,
  "sha": "cd4313921899dbc505a881947e9963474956f929831cb04d100b6c44f734912a",
  "repo_slug": "grzgrzgrz3/pingwa-client",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_grzgrzgrz3_pingwa_bcdbafaf/readme"
}