Recipes

Each recipe shows what integration you need (fields and card template, see Field types) and working code. Tokens everywhere are read from SPARKU_TOKEN_<ADDRESS> — see sparku CLI.

1. Deploy progress in CI with flash on error#

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

#!/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).

#!/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).

#!/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:

# 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).

#!/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).

6. Agent asks before a dangerous command#

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

#!/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.

7. Wrapper if sparku ask … for any command#

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

#!/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

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