CLI reference

Global options

consultchimps [options] [command]

Options:
  -V, --version   output the version number
  --json          print one line of machine-readable JSON for automation
                  instead of the detailed explanation
  --no-log        do not keep a local record of this run
  --log-names     keep input file names, progress details, and error messages
                  in the run record
  --cpu-profile   save a CPU profile of this run beside its record
  -h, --help      display help

Place --json before the subcommand:

consultchimps --json pdf split report.pdf

Machine-readable output

--json works on every command. It replaces the human explanation with exactly one JSON object printed on a single line of stdout, so the output can be piped straight into a JSON parser without stripping prose first.

A successful operation wraps the operation result in an ok: true envelope:

{
  "ok": true,
  "result": {
    "operation": "pdf.split",
    "artifacts": [
      { "kind": "file", "mediaType": "application/pdf", "path": "..." }
    ],
    "warnings": [],
    "metrics": { "inputFiles": 1, "outputFiles": 2, "pages": 2 }
  }
}

A failure wraps the message and its stable error code in an ok: false envelope, and the command still exits with a nonzero status:

{
  "ok": false,
  "error": {
    "message": "Output already exists: outputs/pages/report-page-001.pdf",
    "code": "FILES_OUTPUT_EXISTS"
  }
}

code is a published, stable error reference for expected failures such as FILES_OUTPUT_EXISTS or XLSX_SPLIT_NO_TABLE. It is null for unexpected errors, which have no stable code to depend on. The same object is repeated on stderr so failures remain visible there, but stdout alone is always valid JSON.

Usage errors (an unknown option, an unknown command, or a missing required option) are reported the same way under --json, with the code CLI_USAGE:

{
  "ok": false,
  "error": {
    "message": "error: required option '-c, --column <name>' not specified",
    "code": "CLI_USAGE"
  }
}

--help and --version are unaffected by --json. They print their usual text and exit 0.

Branch on ok rather than parsing the message text:

consultchimps --json pdf split report.pdf -o pages | jq -e '.ok'

Human-readable output

Normal commands are intentionally detailed for non-technical users. A successful operation explains:

1. What ConsultChimps did.
2. What each result count means.
3. Every file that was created.
4. Whether any warnings occurred.
5. Whether the source files were left unchanged.
6. What the user can do next.

Recoverable errors explain what went wrong, suggest safe recovery steps, and include a stable error reference that can be shared with support. Use --json to replace these explanations with the compact structured result needed by an automation.

Long-running operations additionally report progress on standard error while they work: the current stage with counts, such as Reading workbooks 3/14: report.xlsx, updated in place on an interactive terminal and printed as plain lines elsewhere. Progress never appears under --json, so piped output stays clean.

Documents and filenames are untrusted input, and a control character written to a terminal is an instruction rather than a character. Four places carry such text and print its control characters as a visible \uXXXX escape instead: the workbook inspection report, a result's warnings and the paths of the files it created, the progress lines, and the message of a failure. The values are unchanged: --json reports the original text, where JSON's own escaping already makes a control character inert.

Spreadsheet inspection

consultchimps sheets inspect [options] <input>

Options:
  --sheet <name>            describe only this worksheet; repeat for several
  --header-row <number>     one-based header row
  --hidden                  describe hidden worksheets as well
  --samples <number>        sample values per column, 0 to 5 (default: 5)

The command describes an .xlsx or .xlsm workbook and writes nothing: no output file, no directory, and no change to the workbook it read. The report lists each described worksheet with its visibility, the size of its used range, the header row an operation would resolve, the number of data rows below it, and each header with a few of the values stored beneath it, followed by the Excel Tables and named ranges those worksheets contain. The result that closes the report has no artifacts, and its warnings name what a later operation would stumble on: hidden worksheets left out of the description, or a worksheet with no header row to match columns by.

Sample values are the first few distinct non-empty values a column stores, at most five, reported as the workbook holds them. Text is quoted in the report so the number 1 and the text "1" stay apart. --samples 0 reports headers with no values. A count above five is refused with XLSX_INVALID_SAMPLE_LIMIT rather than reduced to five, so the same request means the same thing at every layer.

Sample values and Excel Table column names are quoted, with a quote inside one escaped and a backslash doubled, so one value can never read as two. Worksheet names, headers, and values follow the control-character rule described under Human-readable output, in the report and in the progress lines alike.

--sheet takes one worksheet name and may be repeated, so the workbook can be named either before or after the options:

consultchimps sheets inspect clients.xlsx --hidden --samples 2
consultchimps sheets inspect --sheet North --sheet South clients.xlsx

Under --json the envelope's result carries the whole inspection outcome: a description object holding the worksheets, Excel Tables, and named ranges, and a result object holding the operation result with its metrics and warnings.

Spreadsheet consolidation

consultchimps sheets consolidate [options] <inputs...>

Required:
  -o, --output <path>       output .xlsx file

Options:
  --sheet <names...>        include only these worksheet names
  --header-row <number>     one-based header row
  --hidden                  include hidden worksheets
  --normalize-headers       match headers that differ only in case, spacing,
                            or punctuation
  --map <file>              JSON column mapping applied before the union
  --suggest-map <file>      write a draft column mapping for review
  --no-source               omit file, sheet, and row provenance
  --output-sheet <name>     output worksheet name (default: Consolidated)
  --values                  write values instead of formulas, preserving formatting
  -f, --force               replace an existing output file

--map folds columns that are named differently into one canonical column each, using the versioned JSON document described in Map columns onto one schema. A column no entry claims keeps its own name and is reported as a warning. Two columns of one worksheet folding into one canonical column stop the run.

--suggest-map writes a draft mapping built from the headers that were read and still writes the consolidated workbook. The draft is never applied; it goes through the same never-overwrite rule as any other output, so --force is needed to replace one. --map and --suggest-map cannot be combined in one run.

Spreadsheet worksheet merging

consultchimps sheets merge [options] <inputs...>

Required:
  -o, --output <path>       output .xlsx file

Options:
  --no-index                omit the visible Sheet Index worksheet
  --values                  replace formulas with stored values, preserving formatting
  -f, --force               replace an existing output file

The command copies every source worksheet into a separate tab in resolved input order. Duplicate worksheet names receive a numeric suffix. Source visibility is retained, and the default Sheet Index records each source file, original tab name, final tab name, and visibility.

Spreadsheet splitting

consultchimps sheets split [options] <input>

Required:
  -c, --column <name>       column header used to split rows

Options:
  -o, --output <directory>  output directory (default: <input>-split)
  --output-dir <directory>  alias for --output
  --sheet <name>            use the legacy single-worksheet split mode
  --table <name>            named Excel Table to split instead of the used range
  --range <name>            named range to split instead of the used range
  --header-row <number>     one-based header row
  --hidden                  allow a selected hidden worksheet
  --preserve-workbook       retain the whole workbook (the default)
  --no-preserve-workbook    create a compact data-only single-source workbook
  --values                  replace formulas with stored values, preserving formatting
  --strict                  compare case, whitespace, and value types exactly
  --skip-blank              omit rows whose split-column value is blank
  --prefix <name>           output filename prefix
  -f, --force               replace existing output files

Without --table, --range, or --sheet, the command collects normalized, non-blank values across every worksheet containing the column, then filters a copy of the whole workbook for each value. Worksheets without the column are copied unchanged; pivot tables and their caches are removed with a warning. --table, --range, and --sheet select the established single-source modes.

Consolidation, worksheet merging, and splitting accept --values; inspection creates no workbook, so it has no such option. It removes worksheet and Excel Table formulas while retaining their stored results. The conversion edits the underlying workbook cells rather than reconstructing them, so styles, number formats, dimensions, and workbook layout are preserved. A formula with no stored result becomes a formatted blank cell and produces a warning. Consolidation and compact data-only split outputs already contain values, so the option is explicit but does not otherwise change those files.

Excel unprotection

consultchimps sheets unprotect [options] <input>

Required:
  -o, --output <path>       output .xlsx or .xlsm workbook

Options:
  -f, --force               replace an existing output workbook

The command removes ordinary worksheet and workbook-structure protection without needing the protection password. It never changes the source file. Office files encrypted or password-required to open are not supported.

PDF splitting

consultchimps pdf split [options] <input>

Options:
  -o, --output <directory>  output directory
  --prefix <name>           output filename prefix
  -f, --force               replace existing output files

PowerPoint template inspection

consultchimps pptx inspect-template [options] <template>

Options:
  --template-slide <number>  one-based template slide (default: 1)

The report lists valid placeholder names and occurrence counts, malformed placeholder locations, and unsupported placements. Split-run placeholders are supported.

PowerPoint template population

consultchimps pptx populate [options]

Required:
  --template <path>          source .pptx template
  --data <path>              source .xlsx workbook
  -o, --output <path>        output .pptx presentation

Options:
  --sheet <name>             worksheet containing the records (default: first)
  --template-slide <number>  one-based template slide (default: 1)
  --header-row <number>      one-based row containing field names
  -f, --force                replace an existing output presentation

Place the global --json option before pptx to receive the structured inspection or operation result.

PDF merging

consultchimps pdf merge [options] <inputs...>

Required:
  -o, --output <path>       output PDF file

Options:
  -f, --force               replace an existing output file

Run records

Every command that does work keeps a local record of its run: the machine it ran on, how long each stage and each input took, memory sampled every second, and how it ended. Records stay on your machine and are never uploaded.

A record holds counts, sizes, and timings. It keeps no file names, paths, worksheet names, or cell values unless you add --log-names, which keeps input file names, progress details, and error messages as printed. Options given as switches or numbers are kept as given, such as --limit 7; for options given as text, such as paths and worksheet names, only the fact that they were set is kept. A failed run prints the path of its record.

Records live in %LOCALAPPDATA%\consultchimps\logs on Windows, ~/Library/Logs/consultchimps on macOS, and consultchimps/logs under $XDG_STATE_HOME (default ~/.local/state) elsewhere, or in CONSULTCHIMPS_LOG_DIR when set. The newest 100 runs are kept, none older than 30 days. Turn recording off for one run with --no-log, or for every run with CONSULTCHIMPS_LOG=off.

Exit behavior

Successful commands exit with status 0. Invalid input, discovery failures, unreadable documents, and output-safety failures set exit status 1 and write a detailed explanation to standard error.