Quick start

1. Enable the feature#

Settings > Integrations section > "Custom Integrations" block at the bottom (badge "EXPERIMENTAL") > "Turn On…". A warning appears: the feature is experimental, unexpected behavior and increased CPU and battery usage are possible. The "Turn On" button doesn't respond to Return — you must click it explicitly.

After consent, a "Custom Integrations" section appears in the Settings sidebar and a new-integration wizard opens.

2. Install the CLI#

In the same Settings section — "sparku" line with "Install…" button. It creates a symbolic link /usr/local/bin/sparku pointing to the utility inside SparkU.app. If /usr/local/bin is not writable, macOS will ask for admin password once.

Check that the command is available:

sparku version

3. Create an integration with the wizard#

The wizard offers five templates: "Task with progress", "Server metrics", "Timer", "Build status", "List". Each already contains fields, an indicator, a line, and a card — just give a name and address (slug) or accept the suggested one. "Custom" creates an empty integration without fields.

Let's use the "Build status" template with address build. It already has fields stage (status), branch (text), started (time), link (link), and an "Open" button on the card.

4. Copy the token#

In the integration editor — "Connection" section: the line export SPARKU_TOKEN_BUILD=… and ready examples for curl, Python, Node, Swift. Copy the export and run it in the terminal where you'll test:

export SPARKU_TOKEN_BUILD=spk_your_token

sparku will find this environment variable by the integration address — you don't need to pass the token every time manually.

5. First push#

sparku push build stage=running branch=main started=+0s

The indicator and line of the card on the Island should update. Expand the Island — you'll see the "Build status" card with an "Open" button.

6. Check that everything works#

sparku doctor build

The command prints step-by-step: socket exists, SparkU responds, token is found, integration exists, and what fields it has. If something is wrong — doctor tells you at which step.

7. Clear values#

sparku end build

Clears all values for the integration — the Island will have no data for it (elements with visibility "While there is data" disappear).

The same thing via curl#

Without the CLI, directly through the UNIX socket:

curl --unix-socket ~/.sparku/run/api.sock \
  -H "Authorization: Bearer $SPARKU_TOKEN_BUILD" \
  -d '{"stage": "running", "branch": "main", "started": "+0s"}' \
  http://sparku/v1/integrations/build/fields

Clear values:

curl --unix-socket ~/.sparku/run/api.sock -X DELETE \
  -H "Authorization: Bearer $SPARKU_TOKEN_BUILD" \
  http://sparku/v1/integrations/build/fields

Next steps#

• Concepts — how fields, Island, cards, and tokens work.
• Field types — what you can send in push for each type.
• sparku CLI — all commands and exit codes.