CLI Handbook

01 / Getting started

Install once. Inspect your first file.

With Node.js 20 or newer, install the pinned release and verify the installation:

npm install -g deepbom@1.103.0
deepbom --version
deepbom self-test --compact

For Python, Cargo, standalone binaries, or a graphical application, see installation methods. To run without a global installation, replace deepbom with npx -y deepbom@1.103.0; its first run downloads the package.

Try the small MNIST ONNX sample (26,454 bytes; source and license). Open a terminal in its download directory:

deepbom audit "./mnist-8.onnx" --summary --expected-sha256 2f06e72de813a8635c9bc0397ac447a601bdbfa7df4bebc278723b958831c9bf --offline

The summary identifies the artifact by its full SHA-256 and separates artifact defects, cautions, and evidence gaps. self-test checks the installation; it does not validate the quality of your model.

02 / audit

Choose the depth of static inspection.

deepbom audit "./model.onnx" --summary
deepbom audit "./model.tflite" --summary
deepbom audit "./model.gguf" --scan structure --summary
deepbom audit "./weights.safetensors" --scan integrity --summary

Do not apply --scan structure indiscriminately: formats such as monolithic ONNX, TFLite, and ExecuTorch accept auto or full. Full SHA-256 calculation still reads the complete file, even when numerical payload checks are skipped.

Stable or existing deployment paths cover TFLite, ONNX, GGUF, SafeTensors, Core ML, and ExecuTorch. TensorFlow, Keras, HDF5, PT2, and PyTorch checkpoint support has preview boundaries. Safe-envelope inspection never constructs arbitrary framework objects or proves an executable graph.

03 / model-summary · gguf · explain-rule

Ask a smaller, precise question.

Model structure and serialized storage

deepbom model-summary "./model.onnx" --level operation --format table
deepbom model-summary "./model.gguf" --level storage --format markdown
deepbom gguf "./model.gguf" --tensors --tensor-offset 0 --tensor-limit 20
deepbom audit "./weights.safetensors" --encoding-inventory --compact

Model summaries project the hash-bound Model IR. Serialized storage counts are not trainable parameter counts; the display order is not a runtime schedule. Encoding inventory is supported for GGUF, SafeTensors, ONNX, and TFLite.

Select a section or explain a finding

deepbom audit "./model.onnx" --list-sections
deepbom audit "./model.onnx" --section quantization --json
deepbom audit "./model.onnx" --section model_ir --compact
deepbom explain-rule --list
deepbom explain-rule EA-IOC-0001 --json

Use section names reported for your artifact. --pointer can select a specific RFC 6901 JSON Pointer when you know the returned document's structure. Use a rule ID from your own findings when requesting an explanation.

04 / Evidence files

Save a report for its next consumer.

deepbom audit "./model.onnx" --output-format envelope -o "evidence.json" --no-clobber
deepbom audit "./model.onnx" --output-format json -o "analysis.json"
deepbom audit "./model.onnx" --output-format cyclonedx -o "model.cdx.json"
deepbom audit "./model.onnx" --output-format sarif -o "model.sarif"
deepbom audit "./model.onnx" --render markdown -o "review.md"

-o writes a complete file atomically; --no-clobber refuses to replace an existing destination. Use --output - for stdout. To reproduce timestamped documents, supply a fixed --timestamp or SOURCE_DATE_EPOCH.

deepbom audit "./model.onnx" --output-format cyclonedx --timestamp 2026-09-18T00:00:00Z -o "model.reproducible.cdx.json"

05 / graph · visualize

Export a picture or a document bundle.

deepbom graph "./model.onnx" --view structure --output-format svg -o "graph.svg"
deepbom graph "./model.onnx" --view structure --output-format png -o "graph.png"
deepbom graph "./model.onnx" --view quantization --output-format html -o "graph.html"
deepbom visualize "./model.onnx" --view all --orientation portrait -o "model-views.zip"

graph supports structure, placement, quantization, and architecture views, with SVG, PNG, HTML, Mermaid, DOT, or JSON output.

visualize produces document-oriented Model IR pages with SVG, black-and-white 300-DPI PNG, captions, and an identity-bound manifest. Select all or comma-separated view IDs: identity-boundary, architecture-overview, block-detail, exhaustive, static-runtime, observed-runtime.

Views retain their evidence gaps and loss information. Asking for an observed-runtime view does not create a runtime trace. A document-oriented layout does not establish regulatory approval.

06 / diff · contract capture · verify

Review a change and reconcile its evidence.

deepbom diff "./baseline.onnx" "./candidate.onnx" --summary
deepbom diff "./baseline.gguf" "./candidate.gguf" --tensors --render markdown -o "tensor-changes.md"
deepbom contract capture "./model.onnx" --json -o "baseline.interface-contract.json"
deepbom verify "./model.onnx" --contract "./reviewed.interface-contract.json" --render markdown
deepbom verify "./model.onnx" --bom "./model.cdx.json" --render markdown

diff requires matching supported artifact formats and compares serialized graph, storage, and quantization evidence. It does not establish conversion lineage or a change in model quality.

contract capture records an artifact-derived external-interface baseline. Review it separately before treating it as a production declaration; capture alone is not approval. verify --contract checks the supplied interface declaration. verify --bom reconciles artifact-observable facts in a CycloneDX 1.7 component, with --component-ref available for explicit selection.

A partial or blocked verification has a distinct exit code. It is not silently reported as a pass.

07 / Policies · batch

Make the review policy explicit.

deepbom audit "./model.onnx" --output-format sarif --gate defects -o "findings.sarif" --policy-output "decision.json" --error-format json
deepbom audit "./model.onnx" --output-format envelope --policy engineering -o "engineering-evidence.json"

--gate defects blocks on artifact defects. The engineering profile preserves cautions and gaps without using them as blockers; regulatory also blocks unresolved evidence gaps and does not determine legal compliance. --fail-on high gates by severity. Choose one of --gate, --policy, --review-policy, or --fail-on; they are mutually exclusive.

Successful analysis still writes the requested evidence when the finding policy returns exit code 2. Archive both the evidence and policy decision. Without a selected policy, a completed analysis does not automatically block on its findings.

Process multiple files from a manifest

Save the following as batch.json beside the MNIST sample downloaded in chapter 1. Every entry requires a unique ID, a safe relative path, and the expected SHA-256.

{
  "schema": "deepbom.batch_manifest.v1",
  "artifacts": [{
    "id": "mnist",
    "path": "mnist-8.onnx",
    "expected_sha256": "2f06e72de813a8635c9bc0397ac447a601bdbfa7df4bebc278723b958831c9bf",
    "scan": "auto",
    "output": "envelope"
  }]
}

deepbom batch "./batch.json" --batch-output-dir "./batch-results" --compact -o "batch-summary.json"

Per-artifact results are written to the output directory. Existing result files are not overwritten; use a fresh directory for a new run. Read the batch summary's per-file status and exit codes. Batch entries accept analysis, envelope, cyclonedx, or sarif output and their own scan mode.

08 / Multiple files & immutable sources

Keep sidecars and source identity together.

deepbom audit "./model.onnx" --external-data-dir "./weights" --summary
deepbom audit "./Model.mlpackage" --summary
deepbom audit "./sharded-safetensors" --summary
deepbom audit "./program.pte" --external-data-dir "./sidecars" --summary

Use the complete package or shard directory with its manifests and members. Do not treat one shard or a missing ONNX data sidecar as a complete model.

Pinned remote input

The following templates require replacement of every bracketed value. Mutable branches and unpinned downloads are not accepted as immutable identity.

deepbom audit "hf://owner/repo@<40-hex-commit>/model.gguf" --scan structure --summary
deepbom audit "gs://bucket/model.onnx#generation=<object-generation>" --summary
deepbom audit "https://host/model.onnx#sha256=<64-hex-digest>" --summary

--cache-dir chooses the content-addressed cache. --offline refuses remote access and requires a verified cache receipt for remote inputs. --max-download-gib bounds the download. This does not prevent a package manager such as npx from downloading DEEPBOM itself.

09 / placement · accelerator · explore

Separate a static scenario from a measurement.

deepbom audit "./model.tflite" --target android_mid_a55 --summary
deepbom placement "./model.tflite" --profiles xnnpack_cpu,tflite_coreml_delegate,litert_qualcomm_qnn --compact
deepbom audit "./model.gguf" --context 4096 --batch 1 --state-bits 16 --memory-mib 8192 --summary

A target or memory capacity is a declared scenario. Static cost, eligibility, or memory lower bounds do not identify the actual machine, selected runtime provider, measured latency, or usable capacity.

deepbom accelerator collect nvidia --compact -o "nvidia-profile.json"
deepbom explore "./model.tflite" --request "./redesign-request.json" --compact

accelerator collect nvidia queries the NVIDIA host environment and requires a working NVIDIA driver/tooling setup. Device identifiers are hashed unless --include-device-identifiers is requested. The profile is not evidence that a model executed on that device.

explore accepts standalone TFLite and a separately prepared redesign request. It evaluates static alternatives; it does not retrain or rewrite a model. Imported runtime/build sidecars, including TensorRT, Core ML compute plans, and ExecuTorch build inventories, must satisfy their own artifact identity bindings. See the complete option reference.

10 / capabilities · integrate · mcp

Let a local assistant use the same analyzer.

deepbom capabilities --compact
deepbom capabilities --format agent-json
deepbom integrate codex
deepbom integrate codex --apply
deepbom integrate status codex

Use claude-code or generic in place of codex for another supported skill target. Installation previews changes first; --apply writes only managed skill files.

deepbom integrate remove codex
deepbom integrate remove codex --apply
deepbom mcp

The removal preview identifies managed files; applying removal only deletes unchanged managed files. mcp is a local stdio server, so waiting for client input is normal. It provides deepbom_capabilities, deepbom_audit, deepbom_diff, and deepbom_explain_rule.

By default the MCP server reads within its launch directory. Set DEEPBOM_MCP_ALLOWED_ROOTS in the host configuration for other approved directories. Returned evidence enters the AI conversation even when model bytes stay local. See host-specific connection instructions.

11 / Troubleshooting

Use the exit code and the evidence together.

For automation, --error-format json sends structured errors to stderr while keeping machine evidence on stdout. Inspect the installed release with deepbom --version and its actual command contract with deepbom capabilities --compact.

• Command not found: restart the terminal after installation or use the pinned npx invocation.
• Output already exists: choose a new path when using --no-clobber or a fresh directory for batch results.
• Size or scan policy rejected: use a supported package/shard representation and scan mode. Do not bypass the parser's allocation limit.
• Cannot read stdin: provide a regular file or supported package directory; symbolic stdin is deliberately unsupported.

Static inspection does not run model code or establish task accuracy, clinical validity, runtime placement, measured latency, or regulatory compliance.