---
title: "Getting started"
description: "Install Spool, load sample rows, match them, see each company keep its ID as more rows arrive, and get records out of a text, from the command line, over HTTP and over MCP."
url: https://spool.alexpatow.com/docs/getting-started
docs_index: https://spool.alexpatow.com/llms.txt
---

# Getting started

Install Spool, load sample rows, match them, see each company keep its ID as more rows arrive, and get records out of a text, from the command line, over HTTP and over MCP.

This page installs Spool, makes a project with sample rows, matches them, shows that each company keeps its ID when more rows arrive, and gets three records out of a call note. It takes five minutes. Each step is shown three ways: the command, the HTTP call and the MCP tool. Use the command and read the other two. To find out first whether Spool fits your problem, read [Limits](https://spool.alexpatow.com/docs/limits.md).

## What you need

- Linux on x86-64 or arm64 with version 2.34 or later of the GNU C library, or macOS on Apple silicon. There is no build for Windows, for a Mac with an Intel processor, or for Alpine, whose C library is musl.
- `curl` and `tar`.
- For the step that reads a text, [`uv`](https://docs.astral.sh/uv/), which runs the sample extractor. Every other step works without it.

## Install

```sh
curl -fsSL https://github.com/alexpatow/spool/releases/latest/download/install.sh | sh
```

The script downloads the release for your machine, checks it against its checksum, unpacks it under `~/.local/share/spool/0.1.0` and links `~/.local/bin/spool`. It needs no root and changes nothing else: if `~/.local/bin` is not on your search path, it prints the line that adds it and edits no file. To do it by hand, download `spool-0.1.0-<target>.tar.gz` from the [release](https://github.com/alexpatow/spool/releases/tag/v0.1.0), unpack it and put its `bin` directory on your search path. Keep `bin` and `lib` together: the binary loads the DuckDB library from `../lib`.

```sh
spool --version
```

```text title="Output"
spool 0.1.0
```

## Create a project

```sh
spool init companies
cd companies
```

```text title="Output"
created   companies

  sources/crm.yaml                   the columns of a CRM export
  sources/notes.yaml                 what a record found in a note may say
  entities/company/entity.yaml       what companies are compared by
  entities/company/rules/            three rules, one line of SQL each
  transforms/name_key.sql            the lower-case name the rules compare
  extractors/companies.py            finds company names in text, with a small model
  samples/crm-1.csv                  six rows to load first
  samples/crm-2.csv                  three more for later
  samples/notes-1.txt                a call note that names three companies
  .gitignore                         keeps the server's data, .spool/, out of Git

  cd companies
  spool dev                          runs the server on this machine
  spool load samples/crm-1.csv       loads the first rows, from a second terminal
  spool extract samples/notes-1.txt  finds the companies in the note

The extractor is a Python file, which Spool runs with `uv`. Its first run fetches
about 330 MB, most of it the model, and later runs fetch nothing.
```

A project is a directory of files that you keep in Git. This one declares a source of rows, `crm`, a source of documents, `notes`, and one entity type, `company`. An entity type is a kind of thing you want one ID for. The sample rows:

```csv title="samples/crm-1.csv"
id,name,country
c-1,Acorn Tools,GB
c-2,ACORN TOOLS,GB
c-3,Acorn Tools Ltd,GB
c-4,Larkfield Logistics,GB
c-5,Halden Group,GB
c-6,Halden Group,US
```

## Start the server

```sh
spool dev
```

```text title="Output"
project   .
store     ./.spool/dev.duckdb
applied   d7d4b712d86302152897a67a5924cd1c2e26594e049685c2f007177e20633946 (declared company)
accounts  ./.spool/dev.auth.sqlite
listening on http://127.0.0.1:7765
studio    http://127.0.0.1:7765/
mcp       http://127.0.0.1:7765/mcp
```

It listens on this machine only and asks nobody to sign in. Its data is in `.spool/dev.duckdb`, and it applies changes to the project's files as you save them. The last two lines are the addresses of the browser interface and of the endpoint an agent connects to. Leave it running and open a second terminal in the `companies` directory.

If something else is listening on port 7765, `spool dev` says so and names the fix: add `--listen 127.0.0.1:7766` to the command, set `SPOOL_URL=http://127.0.0.1:7766` in the second terminal, and use that address in the HTTP calls. A second `spool dev` on the same project is refused, because one server runs on a store at a time.

## Load rows

```sh
spool load samples/crm-1.csv
```

```text title="Output"
loaded  6 rows into source `crm`, type `company`: 6 new
next    `spool match` places them in identities
```

Each row is now a record. Loading does not match, and loading the same file again adds nothing.

The same over HTTP:

```sh
curl -s -X POST 'http://127.0.0.1:7765/v1/load?source=crm&entity_type=company' -H 'content-type: text/csv' --data-binary @samples/crm-1.csv
```

The same as an MCP tool call, with one object for each row:

```json title="MCP tool call"
{ "name": "load_rows", "arguments": { "source": "crm", "entity_type": "company",
  "rows": [ { "id": "c-1", "name": "Acorn Tools", "country": "GB" } ] } }
```

## Match

```sh
spool match
```

```text title="Output"
run         2, type `company`
examined    6 records, 4 candidate pairs
judgements  3 match, 1 no_match
placed      6 records, 4 identities created
```

A match run compares the records that are new, with each other and with the ones it has placed before, and puts each in an identity. Four pairs were worth comparing. Three were judged the same company and one was not.

The same over HTTP, where a match is a run:

```sh
curl -s -X POST http://127.0.0.1:7765/v1/match -d '{"entity_type": "company"}'
```

The same as an MCP tool call:

```json title="MCP tool call"
{ "name": "run_match", "arguments": { "entity_type": "company" } }
```

## See the result

```sh
spool show records
```

```text title="Output"
source and key  name                 identity
crm:c-1         Acorn Tools          01a1efc6-41cd-775d-8758-e7300637659a
crm:c-2         ACORN TOOLS          01a1efc6-41cd-775d-8758-e7300637659a
crm:c-3         Acorn Tools Ltd      01a1efc6-41cd-775d-8758-e7300637659a
crm:c-4         Larkfield Logistics  01a1efc6-41cd-775d-8758-e733aa086f7d
crm:c-5         Halden Group         01a1efc6-41cd-775d-8758-e7329447fd9a
crm:c-6         Halden Group         01a1efc6-41cd-775d-8758-e731c61371cb
```

An identity is one company, with its ID and the records that belong to it. The three spellings of Acorn Tools have one identity. Its ID, in the last column, is the company's ID, and it is what other systems store. Yours differs from this one, because an identity's ID is minted when the identity is created. A record has an ID of its own as well, which `spool show records --ids` lists. It is derived from the record's source, its key and its content, so yours are the same as the ones on these pages.

The same over HTTP:

```sh
curl -s 'http://127.0.0.1:7765/v1/records?source=crm'
```

The same as an MCP tool call:

```json title="MCP tool call"
{ "name": "search_records", "arguments": { "source": "crm" } }
```

## Ask why

```sh
spool explain crm:c-5 crm:c-6
```

```text title="Output"
`crm:c-6` belongs to identity 01a1efc6-41cd-775d-8758-e731c61371cb and `crm:c-5` to identity 01a1efc6-41cd-775d-8758-e7329447fd9a.
Run 2 (strategy `rules`) judged them `no_match` (no_match rule `different_country` held).
Both were placed at log position 1 by `engine` (reconcile run 3, "reconcile new records").
By the rules as they are now, block rule `name_prefix` makes them a candidate pair and no_match rule `different_country` holds, so they would be judged `no_match`.

left   34a5d12a-11a0-e461-c6e4-0576f546d165  crm:c-6  identity 01a1efc6-41cd-775d-8758-e731c61371cb
right  38f040c9-82b9-2f94-813b-697309e52dab  crm:c-5  identity 01a1efc6-41cd-775d-8758-e7329447fd9a

features
            left          right
  country   US            GB
  name      Halden Group  Halden Group
  name_key  halden group  halden group

rules as they are now
  block     name_prefix        holds
  no_match  different_country  holds
  match     similar_name       holds

runs that compared them
  run 2  rules  succeeded  block: name_prefix  no_match
```

The two Halden Groups have the same name and different countries. The rule that kept them apart is one line:

```sql title="entities/company/rules/no_match/different_country.sql"
-- A no_match rule says a pair is not the same thing, and wins over any
-- match rule. This one holds only when both rows have a country.
l.country <> r.country
```

The rule that matched "Acorn Tools Ltd" to "Acorn Tools" is one line too:

```sql title="entities/company/rules/match/similar_name.sql"
-- A match rule says a pair is the same thing: here, two names that are
-- close. The similarity is 1 for equal names and 0 for names with nothing
-- in common.
jaro_winkler_similarity(l.name_key, r.name_key) >= 0.92
```

A rule is a SQL condition over two records, `l` and `r`. [Matching](https://spool.alexpatow.com/docs/concepts/matching.md) explains the three kinds.

The same over HTTP:

```sh
curl -s 'http://127.0.0.1:7765/v1/explain?a=crm:c-5&b=crm:c-6'
```

The same as an MCP tool call:

```json title="MCP tool call"
{ "name": "explain_pair", "arguments": { "a": "crm:c-5", "b": "crm:c-6" } }
```

## Send more rows

The second sample file has two names that are spelt wrongly and one company that is new:

```csv title="samples/crm-2.csv"
id,name,country
c-7,Larkfeild Logistics,GB
c-8,Kestrel Analytics,US
c-9,Acorn Tool,GB
```

```sh
spool load samples/crm-2.csv
spool match
```

```text title="Output"
loaded  3 rows into source `crm`, type `company`: 3 new
next    `spool match` places them in identities
run         5, type `company`
examined    3 records, 4 candidate pairs
judgements  4 match, 0 no_match
placed      3 records, 1 identity created
```

```sh
spool show records
```

```text title="Output"
source and key  name                 identity
crm:c-1         Acorn Tools          01a1efc6-41cd-775d-8758-e7300637659a
crm:c-2         ACORN TOOLS          01a1efc6-41cd-775d-8758-e7300637659a
crm:c-3         Acorn Tools Ltd      01a1efc6-41cd-775d-8758-e7300637659a
crm:c-4         Larkfield Logistics  01a1efc6-41cd-775d-8758-e733aa086f7d
crm:c-5         Halden Group         01a1efc6-41cd-775d-8758-e7329447fd9a
crm:c-6         Halden Group         01a1efc6-41cd-775d-8758-e731c61371cb
crm:c-7         Larkfeild Logistics  01a1efc6-41cd-775d-8758-e733aa086f7d
crm:c-8         Kestrel Analytics    01a1efc6-42c0-7776-b736-83fde0cb4498
crm:c-9         Acorn Tool           01a1efc6-41cd-775d-8758-e7300637659a
```

"Acorn Tool" and "Larkfeild Logistics" joined the identities that existed, and those kept their IDs. Kestrel Analytics is new and got a new one. Nothing that was placed before moved.

## Extract records from text

Rows are one way in. The other is text: an extractor reads a document and says where it names a company, and each place becomes a record. The project has a sample document and a sample extractor.

```text title="samples/notes-1.txt"
Call with Dana Reyes on 12 November. She has moved to Acorn Tools Ltd and runs
purchasing there. They now ship through Larkfield Logistics Ltd, and she asked
whether we work with Brightwater Foods Ltd, their new supplier.
```

```python title="extractors/companies.py"
# /// script
# requires-python = ">=3.10,<3.13"
# dependencies = ["fast-gliner>=0.4.1,<0.5"]
# ///
"""Finds the companies a document names, with a small model that runs here.

An extractor reads documents and says where they name something, and each
thing it finds becomes a record. Spool runs this file with `uv`, which
installs what the lines above list. The first run fetches about 330 MB, most
of it the model, and later runs fetch nothing. No document leaves this
machine and there is no key to set.
"""

import sys

from fast_gliner import FastGLiNER
from spool import extractor

# What to look for. On the left is the word the model is given, and the word
# decides what is found: "company" misses most universities, parties and
# charities, and "organization" finds them. Any word will do, "person" or
# "medicine" as well. On the right is the entity type of this project that
# such a find becomes a record of.
LOOK_FOR = {"company": "company"}

# GLiNER small: 245 MB, Apache-2.0, at the version it was tried with.
MODEL = "onnx-community/gliner_small-v2.1"
WEIGHTS = "onnx/model_q4f16.onnx"
VERSION = "8142fb00740ccea973e64b1272949ff48653df5e"

def load():
    """The model: read from this machine if it is here, and fetched if not."""
    files = {"onnx_path": WEIGHTS, "allow_patterns": ["*.json", WEIGHTS], "revision": VERSION}
    try:
        return FastGLiNER.from_pretrained(MODEL, local_files_only=True, **files)
    except FileNotFoundError:
        print(f"Fetching the model {MODEL} (245 MB), once.", file=sys.stderr)
        return FastGLiNER.from_pretrained(MODEL, **files)

# Loaded as the file starts, so that `spool build --install` fetches it too.
model = load()

@extractor
def find(document):
    # The model reads 384 words at a time and ignores the rest, so a long
    # document is read in pieces.
    for piece in document.pieces(300):
        for found in model.predict_entities(piece.text, list(LOOK_FOR)):
            # The model counts in bytes, and Spool in characters.
            start = len(piece.text.encode()[: found["start"]].decode())
            end = start + len(found["text"])
            # `name` is a column of sources/notes.yaml.
            yield piece.mention(LOOK_FOR[found["label"]], start, end, name=found["text"])
```

This extractor is a Python file, which Spool runs with `uv`. It asks a small model, which runs on this machine, where the text names a company, and the text it found is the record's `name`. No document leaves the machine and there is no key to set. The first run fetches about 330 MB, most of it the model, and later runs fetch nothing.

```sh
spool extract samples/notes-1.txt
```

```text title="Output"
source     notes
read       1 document from samples/notes-1.txt
loaded     1 new, 0 already held, 0 new versions
extractor  companies
found      3 records in 1 document: 3 new, 0 already held

  company  Acorn Tools Ltd          notes:notes-1.txt[54-69]
  company  Larkfield Logistics Ltd  notes:notes-1.txt[119-142]
  company  Brightwater Foods Ltd    notes:notes-1.txt[179-200]

next       `spool match` places them in identities
```

Three records came out of the note. Each keeps where it was found: the document and the characters. They are records like the rows, so the same rules match them.

```sh
spool match
```

```text title="Output"
run         10, type `company`
examined    3 records, 6 candidate pairs
judgements  6 match, 0 no_match
placed      3 records, 1 identity created
```

```sh
spool show records --source notes
```

```text title="Output"
source and key              name                     identity
notes:notes-1.txt[54-69]    Acorn Tools Ltd          01a1efc6-41cd-775d-8758-e7300637659a
notes:notes-1.txt[119-142]  Larkfield Logistics Ltd  01a1efc6-41cd-775d-8758-e733aa086f7d
notes:notes-1.txt[179-200]  Brightwater Foods Ltd    01a1efc6-43a9-7403-b9f6-1f8ee76184ed
```

"Acorn Tools Ltd" in the note has the ID that the CRM rows for Acorn Tools have, and Larkfield Logistics has its own. Nothing held Brightwater Foods, so it got a new ID. `spool show records <record>` prints the sentence a record was found in.

The same over HTTP, in two calls: store the document, then run the extractor.

```sh
curl -s -X POST 'http://127.0.0.1:7765/v1/documents?source=notes&key=notes-1.txt' -H 'content-type: text/plain' --data-binary @samples/notes-1.txt
```

```sh
curl -s -X POST http://127.0.0.1:7765/v1/extractions -d '{}'
```

The same as MCP tool calls:

```json title="MCP tool call"
{ "name": "load_documents", "arguments": { "source": "notes",
  "documents": [ { "key": "notes-1.txt", "text": "Call with Dana Reyes on 12 November. ..." } ] } }
```

```json title="MCP tool call"
{ "name": "run_extraction", "arguments": { "extractor": "companies" } }
```

The word the model is given decides what it finds: `LOOK_FOR` in the file gives it "company", and another word finds other things. An extractor is a Python or TypeScript file in `extractors/`, which Spool runs with `uv` or `bun`, so one of those has to be installed for it. [Extraction](https://spool.alexpatow.com/docs/concepts/extraction.md) writes one.

## Connect an agent

The server speaks the Model Context Protocol (MCP) at the `mcp` address it printed. `spool dev` asks for no token. For Claude Code:

```sh
claude mcp add --transport http spool http://127.0.0.1:7765/mcp
```

For Codex:

```sh
codex mcp add spool --url http://127.0.0.1:7765/mcp
```

Then ask it, for example: "Load samples/crm-2.csv into Spool, match it, and tell me why c-5 and c-6 are different companies." The tools it has for that are `load_rows`, `run_match`, `search_records` and `explain_pair`, with `load_documents` and `run_extraction` for text. [MCP](https://spool.alexpatow.com/docs/mcp.md) lists every tool and what an agent cannot do.

## Look at it in a browser

The studio is at [http://127.0.0.1:7765/](http://127.0.0.1:7765/). Its Identities screen lists the six companies:

![The studio's Identities screen, listing six companies with the number of records each has](https://spool.alexpatow.com/images/studio-identities.png)

The studio shows the same records, identities and explanations, and it can merge two identities, split one and undo a change.

## Stop

Ctrl-C in the first terminal stops the server. The data stays in `.spool/dev.duckdb`. To start from nothing, stop the server and delete `.spool`.

## Next

- Point it at your own rows: edit the columns in `sources/crm.yaml` and the rules, then `spool load your-file.csv --source crm`. [Project structure](https://spool.alexpatow.com/docs/project-structure.md) lists every file.
- Write an extractor that asks a model. [Extraction](https://spool.alexpatow.com/docs/concepts/extraction.md)
- What happens when a rule gets better. [Matching](https://spool.alexpatow.com/docs/concepts/matching.md#rules-that-get-better)
- Merge, split and undo. [Identities](https://spool.alexpatow.com/docs/concepts/identities.md)
- Read the IDs from your own code. [Using the IDs](https://spool.alexpatow.com/docs/using-the-ids.md)
