CLI commands and exit codes
Run financial files through the Python or npm CLI with reproducible flags, JSON output and diagnostic commands.
The Python and npm installs both provide a command named openbooks. Use python -m openbooks to invoke the Python command explicitly when both are on your path.
Run a file and find the result
Complete the installation guide, then open a terminal with the input file in the current directory. You can download the sample CSV to follow these commands. For your own file, replace the opening amount, currency, and date order with the verified values for that statement.
python -m openbooks run statement.csv --opening 1000.00 --currency INR --date-order dmy --out output
python -m openbooks engine-info
python -m openbooks doctor --jsonrun writes a decision under --out (default out) and prints its filename. Add --machine for one JSON summary per processed file and a final engine-info line on a completed run. Each summary has file, status, code, and output. Read the file at output for the complete decision.
Open the JSON under output/ and read status before accessing records. A refusal file contains the code, message, and input hash. Both CLIs use the input's SHA-256 hash as the filename. Use separate output directories when comparing different options for the same bytes.
Flags for reproducible runs
| Flag | Effect |
|---|---|
--currency INR | Supply a known currency where required. |
--opening 1000.00 | Supply a verified opening balance. |
--account <id> | Supply an account identifier where supported. |
--date-order dmy | Interpret numeric dates as day-first. Use mdy for month-first. |
--allow-derived-opening | Opt into a calculated opening for supported layouts. |
--no-ocr | Disable OCR for document runs. |
--model (Python), --no-model (npm) | Python opts into the model. The npm CLI opts out of its default document cross-check. |
--python <path>, --timeout <ms> (npm) | Select the interpreter or bound runtime. |
--max-document-bytes <bytes> (npm 0.2.1+) | Limit each serialized proof. The default is 64 MiB. |
Run exit codes
| Code | Meaning | Batch job action |
|---|---|---|
0 | Every file released. | Read the documents and retain their evidence. |
1 | One or more files refused. | Read each result and route refusals to review. |
2 | Invalid command or argument. | Correct the invocation. |
3 | Execution failed, for example because the engine could not open a file or timed out. | Check input paths, installation, and runtime limits. |
In Bash, read the exit code with echo $?. In PowerShell, use $LASTEXITCODE. Check it immediately after running Open Books. With a batch, use the individual result statuses to decide which files you can import.
Run more than one file
Pass multiple paths to run when they share the same options. Run files separately when each needs a different opening balance, or use the Python CLI's report command to process a folder. A params.json in the folder can specify context keyed by filename. See each command's --help for accepted options. The Python CLI also exposes eval for fixture sets and link for payout matching when the optional linker is installed.