# Quick start

> Enable the feature, install sparku, and send your first value to the Island.

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

```bash
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:

```bash
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

```bash
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

```bash
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

```bash
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:

```bash
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:

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

## Next steps

- [Concepts](/docs/api/concepts.md) — how fields, Island, cards, and tokens work.
- [Field types](/docs/api/fields.md) — what you can send in `push` for each type.
- [sparku CLI](/docs/api/cli.md) — all commands and exit codes.