bitpeek
  1. Bitpeek
  2. Tools
  3. CLI

Bitpeek Command-Line Interface Manual

Automate binary inspection, searches, hashing, structure parsing, and atomic patch application in CI/CD pipelines and shell environments.

Read quickstart guide Local processing notes

Installation & Basic Usage

The Bitpeek CLI executable is bundled in the packages/cli package and can be run via Node.js:

# Display version and general help
bitpeek --version
bitpeek --help

Available Subcommands

  • bitpeek inspect <file> [--offset <n>] [--length <n>] [--type <t>] [--endian <le|be>] [--json]
  • bitpeek find <file> (--hex <pattern> | --text <str>) [--limit <n>] [--cursor <n>] [--json]
  • bitpeek strings <file> [--min-length <n>] [--limit <n>] [--json]
  • bitpeek hash <file> [--algorithm <sha256|crc32|crc16>] [--json]
  • bitpeek structure <file> [--format <elf|png|custom-schema>] [--schema <file.json>] [--json]
  • bitpeek diff <reference> <current> [--json] [--check]
  • bitpeek patch verify <patch.json> --source <reference> [--json]
  • bitpeek patch apply <patch.json> --source <reference> --output <result> [--force]
  • bitpeek recipe run <recipe.json> [--input <id=file>...] [--dry-run] [--json]

Standardized Exit Codes

The CLI adheres to strict POSIX exit code conventions for predictable shell integration:

  • 0: Success (including diff runs where differences were detected).
  • 1: Internal error or unclassified I/O error.
  • 2: Invalid command-line usage or missing arguments.
  • 3: Invalid input format, malformed hex string, or out-of-bounds range.
  • 4: Integrity verification failed, precondition check failed, or hash mismatch.
  • 5: Resource budget or file size limit exceeded.
  • 130: Process interrupted by user (SIGINT / Ctrl+C).

Local processing and privacy

The CLI workflow opens the same Bitpeek browser workspace. Selected file bytes, file names, pasted input, searches, edits, hashes, and comparison data are processed in local browser memory and are not sent to a Bitpeek server.

The static guide itself can be read without opening a file or creating an account.

Frequently asked questions

Can I pipe the JSON output into jq?

Yes. When --json is specified, all diagnostics and progress stream to stderr, keeping stdout clean for piping directly into jq.

Does bitpeek patch apply overwrite files by default?

No. The CLI defaults to fail-if-exists for all output files. Overwriting an existing destination requires the explicit --force flag.