Command line

Every spool command, what it takes and what it prints.

spool is one binary. Three of its commands run a server, and the rest either work on a project directory or call a running server over HTTP. spool <command> --help prints what this page says about a command.

CommandWhat it doesWorks on
spool initMakes a project with sample rowsA directory
spool infoLists what a project declares and checks its SQLA directory
spool devRuns the server on this machine and applies file changes as they are savedA directory
spool loadLoads a file of rowsA running server
spool extractStores a text file as a document and runs an extractorA running server
spool matchMatches the records that are newA running server
spool showShows runs, records, identities, documents, review items, drafts and the logA running server
spool explainSays why two records share an identity, or why they do notA running server
spool retractTakes back rows a source no longer holdsA running server
spool buildChecks a project and compiles it into a manifestA directory
spool applyApplies a manifest to a storeA store file
spool serveRuns the server from a manifest and a storeA store file
spool tokenMakes, lists and revokes tokensA store file
spool schemaPrints the JSON Schema of the APINothing
spool benchRuns a benchmark scenarioA directory

The commands that call a server take --url (default $SPOOL_URL, or http://127.0.0.1:7765), --token (default $SPOOL_TOKEN; spool dev asks for none) and --json, which prints what the server answered.

The command line cannot merge, split, undo, decide a review item or approve a draft. Those are calls of the HTTP API, buttons in the studio, and MCP tools.

spool init

spool init [<dir>] [--entity <name>] [--source <name>]

Makes a project in <dir>, or in the current directory: a source of rows and a source of documents, one entity type with its features, a transform, three rules and an extractor. Under samples/ it writes two files of rows, which the rules match as they stand, and a document, in which the extractor finds three records. The entity type is company and the source of rows crm unless the options say otherwise, and the source of documents is notes. The sample rows and the document are about companies whatever the two are called.

spool init companies
cd companies
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.

spool info

spool info [<dir>] [--json]

Lists the project's sources, entity types, features, rules, strategies and extractors, and checks every SQL file on the way. It needs no server.

spool info
Output
project   .
manifest  d7d4b712d86302152897a67a5924cd1c2e26594e049685c2f007177e20633946

entity type `company`
  features  record_id UUID, name VARCHAR, name_key VARCHAR, country VARCHAR
  label     name
  sources   crm, notes
  block     name_prefix
  no_match  different_country
  match     similar_name

extractor `companies` (python, extractors/companies.py)

spool dev

spool dev [<dir>] [--listen <addr>] [--store <path>] [--task-timeout <s>] [--tasks <dir>]

Runs the server from a project directory, with its data in .spool/dev.duckdb. A change to the project's files is applied as it is saved. A change that does not compile is reported, and the last version that did keeps running.

It listens on 127.0.0.1:7765, on this machine only. Nobody signs in and a caller needs no token: every change is recorded under one account, an admin. spool serve is the server that others reach.

spool dev
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

One server runs on a store at a time. A second spool dev on the same project is refused:

spool dev
Output
spool: the store ./.spool/dev.duckdb is open in another process (PID 3635), most likely a `spool dev` that is already running on this project.
One server runs on a store at a time. Use the one that is running, or stop it with Ctrl-C and start this one again.

So is one on another project while the first has the port:

spool init ../other
spool dev ../other
Output
project   ../other
store     ../other/.spool/dev.duckdb
applied   d7d4b712d86302152897a67a5924cd1c2e26594e049685c2f007177e20633946 (declared company)
accounts  ../other/.spool/dev.auth.sqlite
spool: cannot listen on 127.0.0.1:7765: something else is listening there, perhaps a `spool dev` on another project.
Give this one another port by adding `--listen 127.0.0.1:7766` to the command, and point the commands that call it there with SPOOL_URL=http://127.0.0.1:7766.

Ctrl-C stops it. It finishes the runs it was given first.

spool load

spool load <file> [--source <name>] [--type <name>] [--delimiter <c>] [--batch <n>]

Loads a CSV file of rows into a source. - in place of the file reads standard input, and a file whose name ends in .tsv or .tab has tabs between its fields. The source may be left out when the project has one, or when the file is named after it: crm-1.csv and crm.csv are rows of crm. Failing both, it is the source that lists most of the file's columns. The entity type may be left out when one takes rows from the source. Loading does not match. A row that is already held adds nothing, and a row whose content changed under the same key is stored as a new version.

spool load samples/crm-1.csv
Output
loaded  6 rows into source `crm`, type `company`: 6 new
next    `spool match` places them in identities

spool extract

spool extract [<file>...] [--source <name>] [--extractor <name>] [--again]

Stores each file as a document, then runs an extractor over the documents it has not read. A document's key is its file's name. With no file it runs the extractor over the documents that are stored. The source is chosen as spool load chooses it, and --extractor may be left out when the project has one. --again reads every document again. An extractor's first run may fetch what it depends on, as the sample extractor fetches its model. Extraction explains what an extractor is.

spool extract samples/notes-1.txt
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

spool match

spool match [--type <name>] [--rematch] [--strategy <name>]

Starts a match of the records no match has examined yet, waits for it, and prints its report. --rematch examines every record again against the rules as they are now. A rematch suggests merges and makes none. --strategy says who judges: rules, which is the default, or one of the project's strategies for the type.

spool match
Output
run         5, type `company`
examined    9 records, 8 candidate pairs
judgements  7 match, 1 no_match
placed      9 records, 5 identities created

spool show

spool show [<what> [<id>]] [options]

Without <what> it prints the entity types and how much there is of each:

spool show
Output
server     http://127.0.0.1:7765
api        v1, engine 0.1.0, store format 11
manifest   d7d4b712d86302152897a67a5924cd1c2e26594e049685c2f007177e20633946
head       log position 1
documents  1

entity type `company`
  records     9, 0 without an identity
  identities  5
  review      0 items open

extractor `companies` (python, extractors/companies.py)
<what>ListsWith an ID
runs [<run>]The latest runsOne run and what it reported
records [<record>]RecordsOne record with its payload and evidence
identities [<identity>]IdentitiesOne identity with its records, constraints and history
documents [<document>]DocumentsOne document with its text
review [<item>]Review itemsOne item with its records
drafts [<draft>]DraftsOne draft with the changeset it would commit
logThe changeset log

A record is named by its ID or as <source>:<key>, which names the latest version of that row. A record found in a document is named as the lists name it, <source>:<document>[<start>-<end>].

OptionMeaningApplies to
--type <name>Only this entity typeruns, identities, records, review, drafts
--status <status>Only this statusruns, review, drafts
--kind <kind>Only runs of this kind: load, extract, match, reconcile, retractruns
--source <name>Only this sourcerecords, documents
--key <key>Only this key within its sourcerecords, documents
--document <id>Only the records found in this documentrecords
--unassignedOnly records that wait for an identityrecords
--latestOnly the version of each document that nothing replaceddocuments
--idsList each record's ID as wellrecords
--after <id>Continue a list after this ID, or the log after this positionlists
--limit <n>List at most this manylists
spool show runs
Output
run  kind       status     about           started by                                 started
6    reconcile  succeeded                  user:01a1f0a3-6d74-7231-b6c6-61d78b04fd97  2026-11-18T21:50:05Z
5    match      succeeded  company, rules  user:01a1f0a3-6d74-7231-b6c6-61d78b04fd97  2026-11-18T21:50:05Z
4    load       succeeded  companies       user:01a1f0a3-6d74-7231-b6c6-61d78b04fd97  2026-11-18T21:50:05Z
3    extract    succeeded  companies       user:01a1f0a3-6d74-7231-b6c6-61d78b04fd97  2026-11-18T21:50:04Z
2    load       succeeded                  user:01a1f0a3-6d74-7231-b6c6-61d78b04fd97  2026-11-18T21:50:04Z
1    load       succeeded  company         user:01a1f0a3-6d74-7231-b6c6-61d78b04fd97  2026-11-18T21:50:04Z
spool show identities
Output
identity                              name                   members  created at
01a1efc6-41cd-775d-8758-e7300637659a  Acorn Tools Ltd        4        log position 1
01a1efc6-41cd-775d-8758-e731c61371cb  Halden Group           1        log position 1
01a1efc6-41cd-775d-8758-e7329447fd9a  Halden Group           1        log position 1
01a1efc6-43a9-7403-b9f6-1f8ee76184ed  Brightwater Foods Ltd  1        log position 1
01a1efc6-41cd-775d-8758-e733aa086f7d  Larkfield Logistics    2        log position 1
spool show log
Output
position  actor   operations  from             started by                                 reason
1         engine  14          reconcile run 6  user:01a1f0a3-6d74-7231-b6c6-61d78b04fd97  reconcile new records

spool explain

spool explain <record> <record>

Says where each record is and what placed it there, what each run that compared them concluded, the constraints and review items that name them, and what the rules say about the pair as it is now.

spool explain crm:c-1 crm:c-2
Output
`crm:c-2` and `crm:c-1` belong to the same identity, 01a1efc6-41cd-775d-8758-e7300637659a.
Run 5 (strategy `rules`) judged them `match` (match rule `similar_name` held).
Both were placed at log position 1 by `engine` (reconcile run 6, "reconcile new records").
By the rules as they are now, block rule `name_prefix` makes them a candidate pair and match rule `similar_name` holds, so they would be judged `match`.

left   a780fcfe-cb2f-21dd-25ea-11db898fd6a2  crm:c-2  identity 01a1efc6-41cd-775d-8758-e7300637659a
right  ab8e9d59-0aaa-96b9-ddb7-db0bff7a9356  crm:c-1  identity 01a1efc6-41cd-775d-8758-e7300637659a

features
            left         right
  country   GB           GB
  name      ACORN TOOLS  Acorn Tools
  name_key  acorn tools  acorn tools

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

runs that compared them
  run 5  rules  succeeded  block: name_prefix  match

spool retract

spool retract --source <name> --type <name> [<key>...] [--keys <file>] [--reason <text>]

Takes back rows a source no longer holds, by their keys. --keys names a file with one key on each line, and - reads standard input. The rows are taken back, not erased: every version stays in the store, leaves its identity by a changeset, and is examined by no later run. The identity keeps its ID and its other records. Loading a row under the same key again brings every version back. A key the source has no row under changes nothing.

spool retract --source crm --type company c-6 --reason "deleted in the CRM"
Output
run 7: 1 key named, 1 record taken back
1 record left an identity, by the changeset at log position 2

spool build

spool build [<dir>] [--base-image <image>] [--install]

Checks the project and compiles it into .spool/manifest.json, which is what spool serve reads. It writes a Dockerfile if the project has none. --install starts each strategy and extractor once so that uv and bun fetch what they depend on, a model that one loads as it starts with it.

spool apply

spool apply [<dir>] --store <path> [--manifest <path>]

Applies a manifest to a store: declares new entity types, and computes the feature table again for each type whose declaration changed. Identities are not touched. The server must not be running on the store. The store is created if it does not exist.

spool serve

spool serve [--manifest <path>] [--store <path>] [--listen <addr>] [--public-url <url>] [--project <dir>] [--no-studio] [--plain-http] [--task-timeout <s>] [--tasks <dir>]

Runs the server that others reach. It listens on 0.0.0.0:7765, and every caller is a person who signed in or a program with a token. Deploying goes through it.

spool token

spool token add <name> --store <path>, spool token list --store <path> [--json], spool token revoke <name> --store <path>

Makes, lists and revokes the tokens of a server, on the server's machine, whether or not the server is running. add prints the token once and nothing else. A caller sends it as Authorization: Bearer <token>, and what it changes is recorded as agent:<name>.

spool schema

spool schema

Prints the JSON Schema of every value the API takes and returns.

spool bench

spool bench <scenario> [--db <path>] [--seed <n>] [--out <path>] [--list <n>] [--strategy <name>] [--task-timeout <s>] [--tasks <dir>]

Runs a benchmark scenario from the repository: loads each step's files, matches, and scores the identities against the scenario's truth. A scenario with documents is also scored on what its extractors found, and on extraction and matching together. The benchmarks say what each scenario measures.

Environment

VariableMeaning
SPOOL_URLThe server the calling commands reach
SPOOL_TOKENA token for it
SPOOL_STOREThe store file of serve, apply and token
SPOOL_PUBLIC_URLThe address people reach spool serve by
SPOOL_GOOGLE_CLIENT_ID, SPOOL_GOOGLE_CLIENT_SECRETSign-in with Google for spool serve
SPOOL_UV, SPOOL_BUNThe uv and bun commands, if they are not on the search path