ConsultChimps

CLI reference

Commands and options supported by the ConsultChimps executable.

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, a missing required option, a value the CLI parses itself that is not valid, such as a number option given anything but a whole number from 1, conflicting options, or a pattern that matches more than one file for a command that reads one) 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"
  }
}

A value an operation checks itself, such as sheets inspect --header-row 0, keeps that operation's own code, for example XLSX_INVALID_HEADER_ROW.

--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 inputs 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)
  --csv-delimiter <delimiter>  CSV delimiter: comma, semicolon, tab, pipe, or one
                            character (default: guessed)
  --csv-encoding <encoding> utf-8, utf-16le, utf-16be, or windows-1252
                            (default: detected)
  --csv-numbers             read CSV fields that hold only a number as numbers
  --csv-decimal <separator> decimal separator for --csv-numbers (default: .)
  --csv-thousands <separator>  thousands separator for --csv-numbers: , . space
                            apostrophe or none (default: , or . after a , decimal)
  --csv-dates <order>       read CSV dates: iso, dmy, mdy, or ymd

The command describes an .xlsx or .xlsm workbook, or a .csv file read as one worksheet (see CSV files), 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 or .csv 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
  --csv-delimiter <delimiter>  CSV delimiter: comma, semicolon, tab, pipe, or one
                            character (default: guessed)
  --csv-encoding <encoding> utf-8, utf-16le, utf-16be, or windows-1252
                            (default: detected)
  --csv-numbers             read CSV fields that hold only a number as numbers
  --csv-decimal <separator> decimal separator for --csv-numbers (default: .)
  --csv-thousands <separator>  thousands separator for --csv-numbers: , . space
                            apostrophe or none (default: , or . after a , decimal)
  --csv-dates <order>       read CSV dates: iso, dmy, mdy, or ymd
  --output-format <format>  xlsx or csv; must agree with the output name's extension
  --csv-bom <true|false>    start a CSV output with a UTF-8 byte order mark
                            (default: true)

Inputs can mix .xlsx workbooks and .csv files; see CSV files.

--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.

CSV files

Every sheets command but unprotect reads .csv files beside workbooks. Each CSV file is one worksheet named after the file, so _source_sheet names it. A merge copies its rows as they are into a tab of that name. A split of a CSV file writes CSV files, or compact workbooks with --output-format xlsx, since there is no workbook to keep; --preserve-workbook with a CSV input is refused with XLSX_SPLIT_CSV_PRESERVE. The encoding comes from a byte order mark, else UTF-8, else Windows-1252 with a warning; the delimiter is guessed from the first rows. --csv-delimiter overrides the guess, and --csv-encoding the encoding, except that a byte order mark wins over a choice that contradicts it, with a warning.

Every field stays text unless asked. --csv-numbers reads a field that is only a number, such as 1,234.50; leading zeros, currency signs and more than 15 digits stay text. --csv-dates iso reads yyyy-mm-dd, and dmy, mdy or ymd also read dates written in that order. Nothing guesses day and month order, and a field that is not wholly a number or a date is never changed. A converted date is a real Excel date in the output.

sheets consolidate writes CSV when -o ends in .csv or with --output-format csv, and sheets split writes CSV files for a CSV input, or with --output-format csv, which splits compactly: with no source named, every worksheet that carries the column gives one file per value, named <prefix>-<value> - <sheet>.csv when more than one worksheet does. A CSV output uses RFC 4180 quoting, commas and CRLF, is UTF-8 with a byte order mark unless --csv-bom false, writes dates as ISO text, and prefixes an apostrophe to text that would start a formula (=, +, -, @), except text that is only a signed number. A merge cannot write CSV, since its tabs cannot be one file. A name that contradicts --output-format is refused with XLSX_OUTPUT_FORMAT_INVALID.

An .xlsx table larger than a worksheet holds, or with a cell longer than 32,767 characters, is refused with XLSX_OUTPUT_TOO_LARGE. Malformed quoting is refused with XLSX_CSV_MALFORMED, naming the row.

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
  --csv-delimiter <delimiter>  CSV delimiter: comma, semicolon, tab, pipe, or one
                            character (default: guessed)
  --csv-encoding <encoding> utf-8, utf-16le, utf-16be, or windows-1252
                            (default: detected)
  --csv-numbers             read CSV fields that hold only a number as numbers
  --csv-decimal <separator> decimal separator for --csv-numbers (default: .)
  --csv-thousands <separator>  thousands separator for --csv-numbers: , . space
                            apostrophe or none (default: , or . after a , decimal)
  --csv-dates <order>       read CSV dates: iso, dmy, mdy, or ymd

The command copies every source worksheet into a separate tab in input order. Files you name are used in the order you give them. A folder or a quoted pattern adds the files it matches in alphabetical order of their paths, at its place in the list, and a file named twice is used once, where it first appears. 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. A .csv input becomes one tab named after the file; see CSV files.

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
  --csv-delimiter <delimiter>  CSV delimiter: comma, semicolon, tab, pipe, or one
                            character (default: guessed)
  --csv-encoding <encoding> utf-8, utf-16le, utf-16be, or windows-1252
                            (default: detected)
  --csv-numbers             read CSV fields that hold only a number as numbers
  --csv-decimal <separator> decimal separator for --csv-numbers (default: .)
  --csv-thousands <separator>  thousands separator for --csv-numbers: , . space
                            apostrophe or none (default: , or . after a , decimal)
  --csv-dates <order>       read CSV dates: iso, dmy, mdy, or ymd
  --output-format <format>  xlsx or csv; must agree with the output name's extension
  --csv-bom <true|false>    start a CSV output with a UTF-8 byte order mark
                            (default: true)

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 or .csv file
  -o, --output <path>        output .pptx presentation

Options:
  --sheet <name>             worksheet containing the records (default: first;
                             refused for a CSV file)
  --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
  --csv-*                    read a CSV file as described in [CSV files](#csv-files)

A .csv data file is one worksheet, read with the --csv-* flags. A number read by --csv-numbers shows every digit with a point as its decimal mark, a date read by --csv-dates shows as yyyy-mm-dd (yyyy-mm-dd hh:mm:ss with a time), and header names stay as written.

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

The command copies every page of each PDF, one document after another, in input order. Files you name are used in the order you give them. A folder or a quoted pattern adds the files it matches in alphabetical order of their paths, at its place in the list, and a file named twice is used once, where it first appears.

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.

CommandResult
consultchimps logs listLists recent runs, newest first (--limit <count>)
consultchimps logsSame as logs list
consultchimps logs showSummarises the latest run: stages, slowest steps, memory
consultchimps logs show <run>Summarises the run whose id starts with <run>
consultchimps logs pathPrints the folder that holds run records
consultchimps --cpu-profile <command>Also saves a CPU profile that opens in Chrome DevTools

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.

Compose with libraries

Use the focused ConsultChimps TypeScript packages without the CLI.

On this page

Global optionsMachine-readable outputHuman-readable outputSpreadsheet inspectionSpreadsheet consolidationCSV filesSpreadsheet worksheet mergingSpreadsheet splittingExcel unprotectionPDF splittingPowerPoint template inspectionPowerPoint template populationPDF mergingRun recordsExit behavior