Shuv API docs

Shuv puts a message on your phone from anything that can make an HTTPS request: a shell script, a cron job, a CI pipeline or an AI agent. You can answer from the notification, and the sender reads your reply. Use it to hear when long jobs finish, to approve a deploy from your pocket, or to let an agent ask you a question instead of guessing.

Quickstart

  1. Connect your phone. Install Shuv, sign in, and allow notifications.
  2. Create an API key. In the app tap KEYS → create a key, or use the web portal. Give it “send Shuvs”, and “read replies” if the sender should read your answers. Copy the key; it is shown once.
  3. Send a Shuv.
    curl -sS https://shuv.cloud/v1/shuvs \
      -H "Authorization: Bearer $SHUV_KEY" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{"title":"Backup finished","body":"Nightly backup took 12 minutes.","priority":"normal"}'
    Your phone buzzes within seconds. The response contains the Shuv’s id.
  4. Read the reply (needs “read replies” and the same key):
    curl -sS https://shuv.cloud/v1/shuvs/$SHUV_ID/response -H "Authorization: Bearer $SHUV_KEY"
    You get 202 with a Retry-After header until you answer, then 200 with {"data":{"message":"Ship it"}}.
Keep keys secret. Store a key in a file only you can read, or in your CI’s secret store, never in code or chat. Use a send-only key where the sender doesn’t need replies, and revoke keys you no longer use.

The shuv command

A single-file helper (Python 3, no dependencies) that sends Shuvs and waits for replies.

curl -sS -o ~/.local/bin/shuv https://shuv.cloud/docs/shuv.py && chmod +x ~/.local/bin/shuv
mkdir -p ~/.config/shuv && read -rs K && printf %s "$K" > ~/.config/shuv/key && chmod 600 ~/.config/shuv/key   # paste the key, press Enter

shuv "Hello" "It works"                          # send
shuv --high "Disk almost full" "92% on /data"    # high priority
reply=$(shuv --wait 600 "Deploy?" "Ship build 19 to production?")   # wait up to 10 minutes for your answer

With --wait, the command prints your reply and exits 0, or exits 3 if you didn’t answer in time. It reads the key from ~/.config/shuv/key (or $SHUV_KEY_FILE) and refuses a key file other users can read.

Recipes

Tell me when a long command finishes

make release; shuv "make release finished" "exit code $?"

Ask before doing something risky

answer=$(shuv --wait 900 "Run migration?" "Applies 0042 to production. Reply yes to continue.") || exit 1
[ "$(echo "$answer" | tr A-Z a-z)" = "yes" ] || { echo "Not approved: $answer"; exit 1; }
./migrate.sh

Set up quick replies such as “yes” and “no” in the app’s settings so you can answer with one tap.

Cron jobs

0 3 * * *  /usr/local/bin/backup.sh || ~/.local/bin/shuv --high "Backup FAILED" "Check /var/log/backup.log"

GitHub Actions

Save the key as a repository secret named SHUV_KEY, then:

- name: Notify my phone
  if: always()
  run: |
    curl -sS https://shuv.cloud/v1/shuvs \
      -H "Authorization: Bearer ${{ secrets.SHUV_KEY }}" \
      -H "Idempotency-Key: ${{ github.run_id }}-${{ github.run_attempt }}" \
      -H "Content-Type: application/json" \
      -d "{\"title\":\"${{ github.workflow }}: ${{ job.status }}\",\"body\":\"${{ github.repository }}@${{ github.ref_name }}\"}"

Python

import json, os, time, uuid, urllib.request

API, KEY = "https://shuv.cloud", open(os.path.expanduser("~/.config/shuv/key")).read().strip()

def call(method, path, body=None):
    req = urllib.request.Request(API + path, method=method, data=json.dumps(body).encode() if body else None,
        headers={"Authorization": f"Bearer {KEY}", "Content-Type": "application/json", "Idempotency-Key": str(uuid.uuid4())})
    with urllib.request.urlopen(req) as r:
        return r.status, json.loads(r.read() or b"{}"), r.headers

def ask(title, body, timeout=600):
    _, sent, _ = call("POST", "/v1/shuvs", {"title": title, "body": body})
    deadline = time.time() + timeout
    while time.time() < deadline:
        status, data, headers = call("GET", f"/v1/shuvs/{sent['data']['id']}/response")
        if status == 200:
            return data["data"]["message"]
        time.sleep(int(headers.get("Retry-After", 5)))
    return None

print(ask("Pick a color", "red or blue?"))

AI coding agents (Claude Code and others)

Give the agent the shuv command and tell it when to use it, for example: “When a task takes longer than a few minutes, or you need a decision while I’m away, run shuv --wait 600 "<question>" "<details>" and act on the reply.” Agents should never see the key itself; keep it in the key file.

In Claude Code you can also notify automatically with hooks in ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "~/.local/bin/shuv 'Claude finished' \"$PWD\"" }] }],
    "Notification": [{ "matcher": "permission_prompt",
      "hooks": [{ "type": "command", "command": "~/.local/bin/shuv --high 'Claude needs approval' \"$PWD\"" }] }]
  }
}

Reference

Authentication

Send Authorization: Bearer <key>. Keys have scopes: shuvs:write (send) and responses:read (read replies to Shuvs sent with the same key). Keys can expire, and revoking one takes effect immediately.

Send: POST /v1/shuvs

FieldRules
titleRequired, 1–120 characters.
bodyRequired, 1–4000 characters. Title and body together must fit in 3,500 bytes of UTF-8.
prioritynormal (default) or high.

The Idempotency-Key header is required (1–128 characters). Retrying with the same key and the same body returns the original Shuv (200) without sending or charging again, so it is safe to retry after a timeout. A new Shuv returns 201. Each Shuv goes to up to five of your connected phones.

Read the reply: GET /v1/shuvs/{id}/response

200 with {"data":{"id","shuvId","message","createdAt"}} once you reply; 202 with Retry-After (seconds) until then. Wait at least that long between polls.

Errors

Errors look like {"error":{"code":"…","message":"…","requestId":"…"}}. Quote the requestId if you contact support.

StatusMeaning
400 / 422Invalid JSON or fields. The message says which.
401Missing, wrong, expired or revoked key.
402 insufficient_creditsThis month’s allowance and your credits are used up. Nothing was sent.
403The key lacks the scope, or the account is suspended.
409no_devices: no phone is connected (nothing charged); or the Idempotency-Key was reused with a different body.
413Request too large.
429Rate limited. Wait for Retry-After.
503Temporarily unavailable or paused. Retry later with the same Idempotency-Key.

Plans and limits

Each accepted Shuv uses one credit; replies, polling and idempotent retries are free. The Free plan includes 100 Shuvs a month and 1 active API key; Pro includes 10,000 Shuvs a month and 10 active keys. Credit packs add Shuvs, not keys. Credit packs add credits that never expire and are used after the monthly allowance. When both run out, sends are refused with 402; there are no overage charges. Manage your plan in the web portal.

Delivery

Shuvs go through Firebase Cloud Messaging. A Shuv that can’t be delivered is retried and expires after 24 hours. A 201 means Shuv accepted the message, not that the phone has displayed it.

Privacy and encryption

Standard Shuvs are readable by Shuv and by Google’s push service in transit, so don’t send secrets. Optional end-to-end encryption (preview, not independently reviewed) lets agents encrypt to your phone’s public key; see the encrypted-envelope format in the OpenAPI description. Read the privacy policy.

Machine-readable spec

The full API, including the encrypted envelope, is described in OpenAPI 3.