# Recipes

> Ready-made examples — deploy progress, Xcode build, server monitoring, timer, task queue, agent confirmation.

Each recipe shows what integration you need (fields and card template, see
[Field types](/docs/api/fields.md)) and working code. Tokens everywhere are read from
`SPARKU_TOKEN_<ADDRESS>` — see [sparku CLI](/docs/api/cli.md#token).

## 1. Deploy progress in CI with flash on error

**Integration:** `deploy`, card template "Progress". Fields: `progress`
(`progress`), `stage` (`state`: `running`/`done`/`failed`), `title` (`text`).

```bash
#!/bin/bash
# deploy.sh — run in CI
set -euo pipefail

sparku push deploy title="api · prod" stage=running progress=0

total_steps=5
for step in $(seq 1 $total_steps); do
  ./run-step.sh "$step" || {
    sparku push deploy stage=failed
    sparku notify deploy "Deploy failed at step $step" --state failed --color red
    exit 1
  }
  sparku push deploy progress="$(( step * 100 / total_steps ))%"
done

sparku push deploy stage=done progress=100%
sparku notify deploy "Deploy ready" --state done
```

## 2. Xcode build / `swift build`

**Integration:** `build`, template "Status". Fields: `phase` (`state`:
`building`/`testing`/`passed`/`failed`), `title` (`text`).

```bash
#!/bin/bash
# build.sh
sparku push build title="SparkU" phase=building

if ! xcodebuild -scheme SparkU -destination 'platform=macOS' build 2>build.log; then
  sparku push build phase=failed
  sparku notify build "Build failed" --state failed --color red
  exit 1
fi

sparku push build phase=testing
if ! xcodebuild -scheme SparkU -destination 'platform=macOS' test 2>test.log; then
  sparku push build phase=failed
  sparku notify build "Tests failed" --state failed --color red
  exit 1
fi

sparku push build phase=passed
sparku notify build "Build and tests green" --state passed
```

## 3. Server monitoring on Python every N seconds

**Integration:** `server`, template "Meters". Fields: `cpu` (`number`, 0–100, `%`),
`memory` (`number`, 0–100, `%`), `latency` (`number`, ms).

```python
#!/usr/bin/env python3
import http.client, json, os, socket, time

TOKEN = os.environ["SPARKU_TOKEN_SERVER"]

class SparkU(http.client.HTTPConnection):
    def __init__(self):
        super().__init__("sparku")
    def connect(self):
        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        self.sock.connect(os.path.expanduser("~/.sparku/run/api.sock"))

def push(fields):
    api = SparkU()
    api.request("POST", "/v1/integrations/server/fields", json.dumps(fields), {
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    })
    response = api.getresponse()
    response.read()

def read_metrics():
    # replace with real metric collection (psutil, /proc, ssh to prod, etc.)
    import random
    return {"cpu": random.uniform(10, 90), "memory": random.uniform(30, 80), "latency": random.uniform(40, 300)}

while True:
    push(read_metrics())
    time.sleep(5)
```

Run in background: `nohup python3 monitor.py &` or via `launchd`/systemd — the socket
survives script restarts; the next `push` will just restore values.

## 4. Timer / countdown with one push

**Integration:** `timer`, template "Timer". Field: `until` (`time`).

The timer ticks inside SparkU — no need to repeat `push` every second, just one call with
the end time:

```bash
# 25-minute countdown (Pomodoro)
sparku push timer until=+25m

# specific time in ISO 8601
sparku push timer until=2026-09-28T15:00:00Z
```

Cancel the countdown — `sparku end timer`.

## 5. Task queue (list)

**Integration:** `queue`, template "List". Field: `tasks` (`list`).

```bash
#!/bin/bash
# queue.sh — update build task list

tasks_json() {
  cat <<'JSON'
[
  {"title": "iOS build", "subtitle": "step 3 of 5", "value": "60%", "state": "running"},
  {"title": "API tests", "subtitle": "412 of 420", "value": "98%", "state": "done"},
  {"title": "DB migration", "subtitle": "staging", "state": "failed"},
  {"title": "Land deploy", "subtitle": "queued"}
]
JSON
}

sparku push queue "tasks:=$(tasks_json)"
```

`tasks:=...` — the colon before `=` in `sparku push` tells the CLI to parse the value as
JSON, not a string (see [sparku CLI](/docs/api/cli.md)).

## 6. Agent asks before a dangerous command

**Integration:** `agent`, dialogs enabled in settings, card is optional.

```bash
#!/bin/bash
# cleanup-branch.sh — called by an AI agent (Claude Code, Codex, etc.) from shell
set -euo pipefail

if sparku ask agent "Delete branch feature/old and close PR #42?" \
     --accept Delete --decline "Don't touch" --timeout 5m; then
  git push origin --delete feature/old
  gh pr close 42
else
  echo "cancelled by user" >&2
  exit 1
fi
```

Details on `ask` exit codes and the "For AI agents" section — [Questions to User](/docs/api/dialogs.md).

## 7. Wrapper `if sparku ask …` for any command

**Integration:** same `agent` as in recipe 6 — one integration for all confirmations in the terminal.

```bash
#!/bin/bash
# confirm.sh — wrapper: ask and run any command
# usage: ./confirm.sh "Delete node_modules?" rm -rf node_modules

question=$1; shift

if sparku ask agent "$question"; then
  "$@"
else
  echo "cancelled" >&2
  exit 1
fi
```

```bash
./confirm.sh "Restart prod server?" ssh prod 'sudo systemctl restart api'
```