ffprobe for documents. One shell command answers a specific question about a PDF, Office, or iWork\nfile; the answer comes back as JSON on stdout and the exit status carries the verdict.
Reach for it when a task needs facts about a document — how many slides, is it encrypted, does it\nhave macros, is it corrupt, is this really a .pptx — rather than the text inside it. It is safe on\nuntrusted input: nothing is rendered, no macro runs, no external reference is followed.
npx skills add installs this document only, not the binary. Check first:
deckprobe --version\ndeckprobe as written throughout this document.node exists → the command is npx -y @deckflow/deckprobe. Prefix every\nexample below with it. First run downloads the package; later runs are cached.curl --proto '=https' --tlsv1.2 -LsSf https://github.com/deckflow/deckprobe/releases/latest/download/deckprobe-installer.sh | shnpm install -g @deckflow/deckprobecargo install --git https://github.com/deckflow/deckprobe --locked deckprobeIf you cannot get it running, say so and stop. Do not fall back to unzipping the package, grepping\nXML, or parsing PDF bytes by hand — avoiding exactly that is the point of this tool.
\ndeckprobe [-t TARGETS] [-l LEVEL] [-c CONFIDENCE] [--view values] [--pretty] FILE\nStart here when you do not yet know what you need:
\ndeckprobe -t @summary --view values --pretty report.pdf\n--view values returns a compact target -> value map. Drop it when you also need each value's\nconfidence, the path that produced it, and the measured cost.
Check the exit status before parsing stdout. A non-zero status still writes valid JSON, but it is\nan error envelope, not a report.
\n-t accepts short names (slide_count), canonical names (powerpoint.slide_count), and selector\npresets. It is repeatable and comma-separated: -t @header,title,page_count.
| Selector | \nExpands to | \n
|---|---|
@header | \nContainer identity only — format, size, extension match, encryption flag | \n
@default | \nThe driver's defaults for the active level. Used when -t is omitted | \n
@summary | \nIdentity, common metadata, and primary structure | \n
@security | \nEncryption, macros, signatures, external references, active content | \n
@structure | \nFormat-owned counts, names, and dimensions | \n
@assets | \nImages, media, previews, fonts, embedded objects | \n
@quality | \nIntegrity, repair, extension match, conformance | \n
@format | \nEvery format-specific target at the active level | \n
@all | \nEverything available at the active level | \n
@summary deliberately omits a statistic the current driver can only get from a full-file read. PDF\npage count is the notable case — ask for page_count or @structure explicitly.
Never guess a target name. The tool documents itself:
\ndeckprobe targets --format pptx --pretty # ids, aliases, min level, value type, cost class\ndeckprobe formats --pretty # drivers, profiles, support boundaries\ndeckprobe schema --pretty # the authoritative report JSON Schema\nreferences/targets.md has the full catalogue per format if you would rather read than run.
-l / --level picks the budget and which paths are eligible. Accepts h/m/d too.
| Level | \nUse it for | \n
|---|---|
header | \nIdentity and container properties. ~500 ms budget | \n
metadata | \nDefault. Bounded metadata and common structural counts. ~500 ms | \n
deep | \nHigher-cost paths. ~5 s — only when a target's min_level says deep | \n
-c / --confidence filters eligible paths: low < medium < high (default) < exact. Lower it\nwhen a target comes back unresolved and an approximate answer is acceptable; raise it with\n-C target=exact for a single target that must be authoritative.
{\n \"schema_version\": 2,\n \"status\": \"ok\", // \"ok\" | \"partial\" | \"error\"\n \"input\": { \"display_name\": \"deck.pptx\", \"source_kind\": \"local_file\" },\n \"driver\": { \"id\": \"powerpoint\", \"profile\": \"pptx\" },\n \"results\": {\n \"powerpoint.slide_count\": {\n \"status\": \"resolved\", // see the eight values below\n \"value\": 31,\n \"confidence\": \"high\", // none | low | medium | high | exact\n \"path\": \"powerpoint.app_statistics\",\n \"source\": \"docProps/app.xml saved statistic\"\n }\n },\n \"execution\": { \"unresolved_targets\": [], \"actual_cost\": { } },\n \"diagnostics\": []\n}\nA result's status is one of resolved, estimated, planned, unknown, unsupported, invalid,\nbudget_exceeded, failed. Only resolved and estimated carry a value. unknown is the common\none: the path ran and the document simply does not record that fact.
status is ok or partial. partial is not a failure — at least one\nrequested target could not be resolved at the requested confidence, and the rest are still valid.\nCheck execution.unresolved_targets.--strict when an unresolved target must fail the command. The full report is still written,\nand the exit status becomes 5.results is keyed by the canonical target name even when you asked with a short alias.| Status | \nMeaning | \nYour next move | \n
|---|---|---|
0 | \nSuccess | \nParse stdout. Unresolved targets are allowed unless --strict | \n
1 | \nInvalid request or unsupported target | \nYou named a target this format has no path for. Run deckprobe targets --format <fmt> | \n
2 | \nCLI syntax error, or the file is missing/unreadable | \nFix the flags or the path | \n
3 | \nUnsupported or unrecognized format | \nCheck the extension against deckprobe formats | \n
4 | \nMalformed input or budget exceeded | \nGenuinely damaged file, or raise -b/-x/-e/-T. See references/limits.md | \n
5 | \n--strict and a target was unresolved | \nThe report is on stdout; decide whether the missing target matters | \n
6 | \nInternal failure | \nA bug. Report it | \n
printf '%s\\n' '{\"path\":\"a.pdf\"}' '{\"path\":\"b.pptx\"}' | deckprobe --jsonl -t @summary\nOne compact JSON per non-empty input line. A per-record error does not stop the run; the process\nexits with the highest per-record status. Each record is a JSON string path, {\"path\":\"...\"}, or\n{\"name\":\"report.pdf\",\"data_base64\":\"...\"}. Add an id to an object record when the caller\nneeds stable attribution; JSONL error envelopes echo that id and the original path under\ninput.
For bytes on stdin, -n supplies the logical filename that selects the format:
curl -sL \"$url\" | deckprobe -n download.pdf -t @security -\nIt has no renderer, no OCR, no text extraction, and no macro interpreter. It never opens a network\nconnection and never resolves an external reference. Legacy XML iWork packages are rejected by\ndesign — only modern IWA is supported. .xlsb is identity-only. PDF XMP is not merged into the\nmetadata targets.
Routing is by filename extension, then verified against the container. Renaming a .pptx to .docx\nreturns MALFORMED_INPUT, and -f/--input-format is an assertion, not an override — it cannot\nforce an unrelated parser onto a file.
Never parse stderr. Every result, including every error, is one JSON value on stdout.
\nRead these only when you need them:
\nreferences/targets.md — the full target catalogue per format, with aliases and minimum\nlevels. Read before naming a target you have not verified.references/recipes.md — task → command lookup for the common questions.references/output.md — the complete report shape, error codes, and cost accounting, for when\nyou are consuming the JSON programmatically.references/limits.md — budgets, the -b/-x/-e/-T overrides, -O format options, and\nhow to diagnose an exit 4.