Files
paperspec/docs/package/reference/cli.md
T
alexmandClaude 4fb8b4f5a7 Add paperspec correct, check math forms and datasets, and give the tools public names
The work the other paper tools planned for paperspec (paperdesk PLAN M5.4,
paperform PLAN 4.2):

- paperspec correct and paperspec.revision apply proposed corrections to a
  package, folder or zip, and write it only once it validates.
- doc.math.form is checked: label and style commands always, the form's own
  spelling when papermath is installed or forms= is passed.
- paperspec.datasets and seven doc.dataset.* rules check a package's datasets.
- fixtures/invalid gains suspect-witness and math-form-label (33 in all).
- Canonical JSON reads numbers as doubles, so 1e20 round-trips.
- The registries and the JSON-LD context ship in the wheel.
- Public names for what paperdesk and paperform imported as private ones,
  with the old names kept as aliases.
- The text and lossy-projection functions are about three times faster
  through the gate, tested equal to the old code on every code point.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013XwDhn4LkrKQfw4ArDEr2E
2026-10-20 22:10:17 -04:00

5.0 KiB

Command line

One command, paperspec, with seven subcommands. python -m paperspec runs the same program. paperspec --version prints the package version and the Unicode version it pins, and paperspec COMMAND --help prints a command's options, advice and examples.

Command Works Does
validate anywhere the package is installed with its tools extra Validate packages, or run proposed corrections through the gate.
correct anywhere the package is installed with its tools extra Apply proposed corrections to a package and write the corrected package.
load anywhere the package is installed with its tools extra Validate packages and load them into a SQLite database.
check in a checkout Check the whole repository.
build in a checkout Rebuild fixtures/ and vectors/ from their sources.
stress in a checkout Stress the oracle with random inputs.
site in a checkout Build the website into _site/.

A misspelled command gets a suggestion, and an option a command does not know is refused. "In a checkout" means the repository an editable install points at, or else the one around the current folder.

validate

paperspec validate [-h] [--correction PROPOSALS] [--max-size BYTES] PACKAGE [PACKAGE ...]
Option Meaning
PACKAGE A package folder or a zipped package (.sct.zip), unpacked under the specification's path rules first.
--correction PROPOSALS A JSON file holding one proposed correction, or a JSON Lines file of several, run through the gate against the one package given. Each record that would be appended to corrections.jsonl is printed, until one is refused. Nothing is written.
--max-size BYTES Refuse a zipped package that expands past this many bytes (default 1073741824).

Each failure is printed to standard error as package: where: rule: message. Exit status: 0 when everything is valid, 1 when something is refused, 2 for a usage error.

correct

paperspec correct [-h] --correction PROPOSALS [--out PATH] [--answered SUSPECT] [--asset FILE] [--max-size BYTES] PACKAGE
Option Meaning
PACKAGE A package folder or a zipped package. It is validated first.
--correction PROPOSALS A JSON file holding one proposed correction, or a JSON Lines file of several, applied in order. Nothing is written unless every one passes the gate.
--out PATH Write the corrected package here, a folder, or a zip for a zipped package, which must not exist. By default PACKAGE is replaced.
--answered SUSPECT The ID of a suspect the corrections answer, which leaves suspects.jsonl. Repeat for several.
--asset FILE A file to add under assets/ as <sha256>.<extension>, such as a crop a correction's evidence names. Repeat for several.
--max-size BYTES As for validate.

The corrected package is validated before it replaces anything. Each record appended to corrections.jsonl is printed, one per line; standard error names the derived lines and datasets left out because they read corrected text, and ends with the document's new revision and package hash. A refusal is printed as validate prints it, and nothing is written. Exit status: 0 when the corrections were applied, 1 when the package or a proposal is refused, 2 for a usage error.

load

paperspec load [-h] --sqlite DATABASE [--bundle] [--built-from REV] [--store STORE] [--max-size BYTES] PACKAGE [PACKAGE ...]
Option Meaning
PACKAGE A package folder or a zipped package. Every package is validated first, and nothing is loaded if any fails.
--sqlite DATABASE The database file, created with the tables of sql/ if it does not exist. Files with no table of their own are copied into DATABASE.assets/.
--bundle Build a new scienting-bundle/1 file with the full-text search index. Needs --built-from.
--built-from REV With --bundle: the store revision the packages come from.
--store STORE With --bundle: the store's name (default: the packages' common store).
--max-size BYTES As for validate.

check

paperspec check [-h] [--quick]

--quick skips the byte-for-byte rebuild. Exit status: 0 when every check passed, 1 otherwise.

build

paperspec build [-h] [--out DIR]

Without --out it rewrites fixtures/ and vectors/ in the checkout; with it, it builds into DIR instead.

stress

paperspec stress [-h] [--seed SEED] [--rounds ROUNDS]

--seed sets the random seed (default 20261014) and --rounds the cases per property (default 200). Exit status: 0 when every property held, 1 otherwise.

site

paperspec site [-h] [--out DIR] [--base-url URL]

--out sets the output folder, which must not be the repository or contain it (default _site/ in the checkout). --base-url sets the site's address for canonical links (default https://paperspec.scient.ing).