CLI reference

This page is generated at build time from the output of the installed CLI, so it always matches the code. Version: 0.3.2. For exit codes see Exit codes.

sciproof --help

usage: sciproof [-h] [--version]
                {capture,verify,suggest-inputs,sign,badge,record,update,calibrate,diff,list,export,check-policy,inspect}
                ...

Record computational experiments and create verifiable evidence for them.

positional arguments:
  {capture,verify,suggest-inputs,sign,badge,record,update,calibrate,diff,list,export,check-policy,inspect}
    capture             run a command once and record evidence
    verify              check a manifest (integrity by default, re-execution only with
                        --rerun)
    suggest-inputs      run a Python command once and list files it read that are not
                        declared
    sign                sign a manifest with an OpenSSH private key (writes
                        <manifest>.sig)
    badge               verify a manifest and write a static SVG badge with the result
    record              capture an experiment without declaring files: inputs and
                        outputs are detected
    update              capture the recorded experiment again (re-baseline) and show
                        what changed
    calibrate           run the recorded command several times and measure how much
                        its outputs vary
    diff                compare two manifests: what changed between two recorded runs?
                        (executes nothing)
    list                list the manifests in a directory; with --check, verify all of
                        them (no rerun)
    export              write a manifest in another format (in-toto Statement v1,
                        OpenLineage events)
    check-policy        validate a policy file and list its rules (nothing is
                        verified)
    inspect             show a readable summary; never executes anything

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

sciproof capture --help

Runs the command once and writes NAME.sciproof.json.

usage: sciproof capture [-h] --name NAME [--input PATH] [--output PATH]
                        [--output-numeric PATH] [--rtol RTOL] [--atol ATOL]
                        [--tolerance OUTPUT SETTINGS] [--timeout SECONDS]
                        [--max-log-bytes MAX_LOG_BYTES] [--claim OUTPUT EXPRESSION]
                        [--note TEXT] [--record-hardware] [--force] [--allow-nonzero]
                        ...

Run COMMAND once in the current directory and write NAME.sciproof.json. Everything
after '--' is the command (it is not run through a shell).

positional arguments:
  -- COMMAND [ARGS...]  the command to run

options:
  -h, --help            show this help message and exit
  --name NAME           experiment name (also names the manifest)
  --input PATH          declare an input file or directory (hashed before and after
                        the run); repeatable
  --output PATH         declare an output file or directory compared by exact hash;
                        repeatable
  --output-numeric PATH
                        declare a .json/.csv/.tsv output compared with a numeric
                        tolerance; repeatable
  --rtol RTOL           relative tolerance for numeric outputs (default 1e-09)
  --atol ATOL           absolute tolerance for numeric outputs (default 0.0)
  --tolerance OUTPUT SETTINGS
                        a tolerance for one --output-numeric file instead of
                        --rtol/--atol, for example --tolerance out/loss.csv 'rtol=1e-3
                        atol=1e-6' (either setting may be left out); repeatable
  --timeout SECONDS     stop the command after this many seconds (no evidence is
                        written)
  --max-log-bytes MAX_LOG_BYTES
                        keep at most this many bytes of stdout and of stderr in the
                        manifest
  --claim OUTPUT EXPRESSION
                        record a checkable claim about a value in a declared
                        .json/.csv output, for example --claim out/metrics.json
                        '$.accuracy >= 0.9' (operators: == != < <= > >= and '~=' with
                        rtol=/atol=); verify checks it; repeatable
  --note TEXT           free text stored in the manifest (why this run was made, what
                        to look for; at most 2000 characters, never interpreted)
  --record-hardware     also record the CPU count, processor and NVIDIA GPUs (via
                        nvidia-smi); no host name, user name or serial numbers; a
                        rerun then reports differences
  --force               overwrite an existing manifest
  --allow-nonzero       exit with status 0 even if the command failed (evidence is
                        written either way)

sciproof verify --help

Integrity by default; --rerun executes the recorded command.

usage: sciproof verify [-h] [--rerun] [--yes] [--strict-env] [--clean-env]
                       [--pass-env NAME] [--allowed-signers FILE] [--timeout SECONDS]
                       [--json] [--format {text,json,markdown,junit}] [--policy FILE]
                       [--save-json FILE]
                       manifest

positional arguments:
  manifest

options:
  -h, --help            show this help message and exit
  --rerun               EXECUTE the recorded command again and compare results (runs
                        arbitrary code with your permissions)
  --yes                 do not ask for confirmation before --rerun
  --strict-env          with --rerun: report INCONCLUSIVE if the environment differs
  --clean-env           with --rerun: give the command only a minimal environment
                        (PATH, temp directories, numerics-related variables) instead
                        of all of yours, including credentials
  --pass-env NAME       with --clean-env: also pass this environment variable;
                        repeatable
  --allowed-signers FILE
                        also check the signature <manifest>.sig against this OpenSSH
                        allowed-signers file; a missing signature is INCONCLUSIVE, a
                        wrong one FAIL
  --timeout SECONDS     stop the rerun after this many seconds (default 3600.0)
  --json                print the report as one JSON object (same as --format json)
  --format {text,json,markdown,junit}
                        report format: text (default), json, markdown for CI summaries
                        (for example: >> $GITHUB_STEP_SUMMARY) or junit XML for CI
                        test viewers; exit codes are the same
  --policy FILE         also check the rules of this policy file (TOML) against the
                        evidence; see docs/POLICY.md
  --save-json FILE      also write the JSON report to this file (whatever --format
                        prints)

sciproof inspect --help

Never executes anything.

usage: sciproof inspect [-h] manifest

positional arguments:
  manifest

options:
  -h, --help  show this help message and exit