afpdf CLI reference
Extract PDF articles using typed, configurable processing.
afpdf is compiled from a closed cli-spec-v1 registry: one source for argv parsing, typed invocation values, which parameter combinations are legal, output contracts, and help. An invocation runs only when it matches exactly one registered combination.
Global arguments
AFDATA registers these itself, so the syntax in Commands leaves them out.
| Argument | Where | What it does |
|---|---|---|
--help | every command | Every legal shape of that command, complete, plus its subcommands. JSON by default; --output plain for a terminal. |
--version | afpdf only | Name, version, and build identity as one protocol result. |
--docs | afpdf only | This document, rendered from the registry. |
--output <FORMAT> | per output contract | Render as json, yaml, plain (default json). |
--output-to <DESTINATION> | per output contract | Route results and diagnostics to split, stdout, stderr (default split). |
--stdout-file <PATH>, --stderr-file <PATH> | per output contract | Append that stream to a file instead. |
Success output is protocol events, on those terms, unless a command’s own Output line says otherwise.
A shape is one legal set of arguments that may appear together, under a stable id. Where a command has more than one, each id is a heading below. --help returns them all at once, so discovering a command costs one call; there is no recursive mode across commands, and this document is that view.
Commands
afpdf config get— Get one effective configuration value by dot path.afpdf config set— Persist a typed configuration value atomically after validation. Only overrides are saved.afpdf config show— Show effective configuration, including defaults, without creating a file.afpdf config unset— Remove a saved override and restore its default.afpdf engine install— Download the pinned PDFium build into the install directory, verify its checksum, and probe it.afpdf engine status— Report which PDFium library would load, whether it loads, and this platform’s limits.afpdf extract— Extract article text and structure; configure processing and optional basic evidence with config keys.afpdf worker— Internal one-document worker; JSON request on stdin and AFDATA reply.
afpdf config get
Get one effective configuration value by dot path.
afpdf config get [--config <PATH>] <KEY>
| Argument | Meaning |
|---|---|
--config | JSON configuration file; default .afpdf/config.json in the current directory. |
afpdf config set
Persist a typed configuration value atomically after validation. Only overrides are saved.
config_set_value — Set a schema-typed value or an explicitly typed value.
afpdf config set [--config <PATH>] <KEY> <VALUE>... [--value-type <auto|string|number|bool|json>]
config_set_null — Set an optional configuration section to null without a value argument.
afpdf config set [--config <PATH>] <KEY> --value-type null
Arguments across every shape above:
| Argument | Meaning |
|---|---|
--config | JSON configuration file; default .afpdf/config.json in the current directory. |
VALUE | Typed replacement; inferred from the config schema unless –value-type is supplied. |
afpdf config show
Show effective configuration, including defaults, without creating a file.
afpdf config show [--config <PATH>]
| Argument | Meaning |
|---|---|
--config | JSON configuration file; default .afpdf/config.json in the current directory. |
afpdf config unset
Remove a saved override and restore its default.
afpdf config unset [--config <PATH>] <KEY>
| Argument | Meaning |
|---|---|
--config | JSON configuration file; default .afpdf/config.json in the current directory. |
afpdf engine install
Download the pinned PDFium build into the install directory, verify its checksum, and probe it.
afpdf engine install [--config <PATH>] [--set <KEY=VALUE>...] [--force]
| Argument | Meaning |
|---|---|
--config | JSON configuration file; default .afpdf/config.json in the current directory. |
--set | Override one typed config key for this invocation; repeat for more keys. Does not save. |
--force | Replace an installed library even when it already matches the pinned build. |
afpdf engine status
Report which PDFium library would load, whether it loads, and this platform’s limits.
afpdf engine status [--config <PATH>] [--set <KEY=VALUE>...]
| Argument | Meaning |
|---|---|
--config | JSON configuration file; default .afpdf/config.json in the current directory. |
--set | Override one typed config key for this invocation; repeat for more keys. Does not save. |
afpdf extract
Extract article text and structure; configure processing and optional basic evidence with config keys.
afpdf extract <PDF> [--config <PATH>] [--set <KEY=VALUE>...]
| Argument | Meaning |
|---|---|
--config | JSON configuration file; default .afpdf/config.json in the current directory. |
--set | Override one typed config key for this invocation; repeat for more keys. Does not save. |
afpdf worker
Internal one-document worker; JSON request on stdin and AFDATA reply.
afpdf worker
Output: protocol events; --output json (default json), --output-to split (default split).
Exit codes
| Code | Meaning |
|---|---|
| 0 | The command ran and succeeded. |
| 1 | The command ran and failed. The event carries a domain error.code. |
| 2 | The invocation was rejected before anything ran. error.code is one of the cli_* codes below. |
The split is the useful one for a caller: exit 2 means the call was never made, so retrying it unchanged cannot help, while exit 1 means it was.
CLI errors
Every structural failure emits one strict JSON kind:"error" event on stderr, leaves stdout empty, and exits 2. The code names the failure — cli_unknown_argument for an unknown spelling, cli_unregistered_combination for registered arguments in a mixture that is not, and one each for cli_unknown_command, cli_missing_argument_value, cli_invalid_argument_value, cli_duplicate_argument, cli_unexpected_positional, and cli_invalid_utf8. message identifies a safe argument spelling or the failure category and hint gives the command to run next; neither ever quotes a raw value, including secrets. These are decided before any config, secret source, filesystem, network, or domain I/O.
Two exit-1 codes describe the tool itself rather than the call: cli_invocation_invalid means the program misread its own resolved invocation — an unknown action id, or an argument id the selected combination cannot produce — and output_setup_failed means an output sink (--stdout-file, --stderr-file, stream redirection) could not be established. Both are defects to report, not inputs to correct; retrying the same command cannot help.
Domain failures (exit 1) carry their own stable error.code instead, drawn from whatever this tool defines rather than from the cli_* set. Error events are routinely logged, so a message never quotes a value that came from an argument able to carry a credential — a header, a cookie, a token, a password, a proxy URL, an environment value, a form field. Such an error names the argument and the shape that was wrong, and stops there. A value that cannot be a secret — a path, a dot-path, a session name — is quoted, because an error that cannot say which one it means is not worth logging either.