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

104 lines
5.0 KiB
Markdown

# 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`](#validate) | anywhere the package is installed with its `tools` extra | Validate packages, or run proposed corrections through the gate. |
| [`correct`](#correct) | anywhere the package is installed with its `tools` extra | Apply proposed corrections to a package and write the corrected package. |
| [`load`](#load) | anywhere the package is installed with its `tools` extra | Validate packages and load them into a SQLite database. |
| [`check`](#check) | in a checkout | Check the whole repository. |
| [`build`](#build) | in a checkout | Rebuild `fixtures/` and `vectors/` from their sources. |
| [`stress`](#stress) | in a checkout | Stress the oracle with random inputs. |
| [`site`](#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
```text
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
```text
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
```text
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
```text
paperspec check [-h] [--quick]
```
`--quick` skips the byte-for-byte rebuild.
Exit status: 0 when every check passed, 1 otherwise.
## build
```text
paperspec build [-h] [--out DIR]
```
Without `--out` it rewrites `fixtures/` and `vectors/` in the checkout; with it, it builds into `DIR` instead.
## stress
```text
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
```text
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`).