Skip to main content
SpoolSync
npm package

SpoolSync on the command line

@spoolsync/cli runs the same matching, planning and export code as this site, for terminals, scripts and scheduled jobs.

View on npmSource

Requires Node.js 20 or newer.

Install
npm install --global @spoolsync/cli
Check it works
spoolsync --help

Example output

6 spools in 2 inventories; 5 groups, 1 match suggestions.  spoolman: 2 updates, 0 creates  spoolio: 1 updates, 1 creates1 field conflicts remain unresolved; those values will be left as-is.Dry run only. Add --output-dir <dir> to write inventory files.

  • Dry run by default

    Without --output-dir or --apply, SpoolSync only prints the plan.

  • Files are never pushed

    --apply needs --spoolman-url. Exports are only ever written to your output folder.

  • Unresolved stays put

    A conflict you haven't resolved is left as-is and counted in the summary.

Quick start

Compare two inventories

Export from each app, then point SpoolSync at the files.

  • 1

    Export

    Download an export from at least two apps: Spoolman, Spoolstock, Spoolio or TigerTag.

  • 2

    Preview

    Run spoolsync with a flag per file. You get the updates and creates per service.

  • 3

    Resolve

    Pick a source for any conflicting field with --resolve, and add --create-in for missing spools in writable services.

  • 4

    Write

    Add --output-dir for updated import files, or --apply to update Spoolman directly.

Recipes

Examples

Hover a command to copy it, then swap in your own file names.

Preview a plan

Writes nothing

Compare three exports and see what would change.

~/spools — preview
spoolsync --spoolman spoolman.json --spoolstock spoolstock.csv --spoolio spoolio.json

Write updated files

Writes ./updated

Use Spoolstock values to resolve conflicts, add missing spools to Spoolio, and save updated import files.

~/spools — update-files
spoolsync --spoolman spoolman.json --spoolstock spoolstock.csv --spoolio spoolio.json --resolve material=spoolstock --create-in spoolio --output-dir ./updated

Update Spoolman directly

Writes to Spoolman

Load Spoolman over the network and write the changes back. Needs --apply.

~/spools — apply
# only if your server needs a tokenexport SPOOLMAN_TOKEN=your-tokenspoolsync --spoolman-url http://spoolman.local --spoolstock spoolstock.csv --apply

Use in scripts

Writes nothing

Print the plan as JSON and pipe it into your own tooling.

~/spools — json
spoolsync --spoolman spoolman.json --spoolio spoolio.json --json | jq '.changes'

Reference

Options

Every flag the CLI accepts.

Inputs

Provide at least two.

--spoolman <file>
Spoolman JSON or CSV export.
--spoolstock <file>
Spoolstock CSV export (read-only source).
--spoolio <file>
Spoolio JSON export.
--tigertag <file>
TigerTag .ttag backup or JSON export.
--spoolman-url <url>
Load Spoolman directly over the network instead of from a file.
--spoolman-token <token>
API token for a protected Spoolman. Can also be set with the SPOOLMAN_TOKEN environment variable.

Planning

Optional: decide conflicts and matches.

--resolve <field=source>
Where a field conflicts, take the value from the named source, e.g. material=spoolman. Repeatable.
--confirm <pair>
Confirm a suggested match, written source:id,source:id. Repeatable.
--reject <pair>
Reject a suggested match, written source:id,source:id. Repeatable.
--create-in <sources>
Create spools in loaded writable sources (comma-separated; not Spoolstock).

Output

Nothing is written unless you ask.

--output-dir <dir>
Write updated import files for supported loaded sources into this folder.
--apply
Write the planned changes to Spoolman. Only works with --spoolman-url.
--json
Print the plan as JSON, for scripts.
-h, --help
Show usage.

Good to know

Notes

  • Use --spoolman-url or --spoolman <file>, not both. Each source can be given once.
  • --create-in and --resolve need the named source loaded.
  • Resolvable fields: vendor, material, name, colors, diameter, density, temperatures, weights, location, price, purchase date, comment and archived.
  • Spoolstock is read-only: its CSV is an input and no Spoolstock file is generated. Updated files for supported services are named spoolman-spools.json, spoolio.json and tigertag-spoolsync.ttag.
  • The exit code is non-zero if an option is invalid or any Spoolman apply step fails.
  • Prefer a UI? The web app does the same thing in your browser.