Reference
CLI Reference
All pluck subcommands grouped by purpose.
Default – pluck <uri>
The primary command. With no subcommand, pluck runs the full pipeline against a URI and prints the result.
Shell
pluck https://news.ycombinator.com
pluck https://api.example.com/items --format json
pluck ./call.wav --sense dtmf
pluck postgres://localhost/app --format csv -o rows.csv
Every top-level flag documented on pluck help works here: --format, --preset, --template, --mode, --sense, --dry-run, --policy, -o / --output, and many more. Piping is first-class – every output format is a string.
Batch + streaming
| Command | Purpose |
|---|---|
pluck batch <uris...> | Run the pipeline across many URIs with bounded concurrency. Yields one BatchResult per URI. |
pluck stream <uri> | Yield the result as chunks over stdout for pipe-friendly streaming. |
pluck watch <uri> | Poll the URI on an interval, emit a WatchEvent on change. |
pluck listen <uri> | Reactive: poll the URI and fire a handler when a sense condition fires. |
Shell
pluck batch https://hn.example.com/{1..50} --concurrency 5 --format json
pluck stream https://example.com --format markdown | my-renderer
pluck watch https://status.example.com --interval 30s --on-change "./alert.sh"
pluck listen mic://input --on ultrasonic --action webhook:https://hooks.example/alert
Registry introspection
Find out what Pluck can do without leaving the terminal.
| Command | Purpose |
|---|---|
pluck connectors | List every registered connector with its URI schemes. |
pluck sensors | List every registered sensor. 14 built-ins. |
pluck actors | List registered actors for the act phase. |
pluck presets | List available output presets (blog, notes, social, rag, dataset, report). |
pluck formats | List registered output formats (12 built-ins + any custom). |
pluck recipes | List recipes discoverable on the current filesystem / user config. |
pluck signatures | List community signature packs loaded via @sizls/signatures-*. |
pluck keys | Manage API / signing keys. |
pluck doctor | Self-diagnose – check Node version, peer deps, signing keys, allowed paths, policy file. |
Introspection primitives
Three pre-flight commands for understanding a source without running the full pipeline.
| Command | Purpose |
|---|---|
pluck probe <uri> | HEAD-only check. Returns source type, content type, estimated cost, recommended format. |
pluck context <uri> | "Where am I?" – schema.org, OG tags, robots.txt, sitemaps, known extractors, PII likelihood. |
pluck dowse <uri> | Zero-config signal reconnaissance. Runs all sensors in fast mode, ranks findings by confidence. |
Phase-specific commands
| Command | Purpose |
|---|---|
pluck shape <args> | Run the shape phase. Covers --diff, --from-api, and --from-file modes. |
pluck snitch <url> | Privacy audit any URL. Returns a forensic report (Ed25519-signed when --signing-key is passed). |
pluck speak <feature> <json> | Inverse of sense – encode JSON as ultrasonic / DTMF / Morse. Returns base64 WAV. |
pluck radio <capture> | Decode RF protocols from SDR captures. ADS-B aircraft decoder ships today. |
pluck deepfake <video> | Forensic deepfake verdict – rppg pulse + rolling-shutter + formant drift. |
pluck audit-ads <uri> | Scan for ad-tracking ultrasonic beacons (Lisnr / Silverpush / SonicNotify). |
pluck sense-diff <a> <b> | "Is this recording edited?" – diff two signals. |
Act + policy + schedule
| Command | Purpose |
|---|---|
pluck undo <receipt> | Reverse a previously-signed action. Validates receipt, finds the actor, runs inverse. |
pluck policy <file> | Validate a .pluckpolicy.yaml file or print the currently-loaded policy. |
pluck verify <file> | Verify a signed receipt (or chain of receipts) against a public key. |
pluck schedule <recipe> <cron> | Register a cron-driven pipeline run. |
Studio + dev loop
| Command | Purpose |
|---|---|
pluck studio | Launch the time-travel devtools – every pipeline run is replayable, every phase is scrubbable. |
pluck record <uri> | Record a deterministic fixture for the pipeline (VCR-style). |
pluck record-flow <uri> | Record an interactive flow (clicks, form fills) into a runnable recipe. |
pluck replay <fixture> | Replay a recorded fixture deterministically. |
pluck simulate <recipe> | Dry-run a recipe against fixtures or LLM-synthesised fake data. |
pluck repl | Open a Node REPL with pluck in scope. |
pluck protocol | Inspect the .well-known/pluck.json protocol descriptor for a URI. |
pluck typecheck [files...] | Static validator for pluck() / pluck.act() / pluck.sense() calls. Catches typos in URI schemes + format strings at build time. Recurses through .ts / .tsx / .js / .jsx / .mjs / .cjs; skips node_modules, dist, build, etc. Supports --json for CI, --strict to treat warnings as errors, --extra-scheme (repeatable or comma-delimited) to allowlist custom-connector schemes. Exits 1 on any error-level diagnostic, 2 on scan failure. |
Fleet ops (SSH)
| Command | Purpose |
|---|---|
pluck tail <ssh-uri> | Multiplex tail -F across a fleet via brace expansion. Coloured by host. Supports --grep, --timestamp, --json, --reconnect-*, --multiline-pattern. |
pluck driftwatch <fleet> | Detect config drift across SSH hosts. DSSE-signed receipts + Merkle-chained audit log. |
pluck query "<sql>" <ssh-uri> | osquery-style SQL over a fleet. --format jsonl|json|csv|table (default jsonl). Routes through the shared SSH connection pool, so repeat invocations against the same fleet skip per-host re-handshake. |
See Recipe: DriftWatch Fleet for the full story on signed receipts + Merkle chain + verify-log.
Help + version
| Command | Purpose |
|---|---|
pluck --version | Print the installed version. |
pluck --help | Top-level help with the full flag list. |
pluck <cmd> --help | Per-command help – flags, examples, exit codes. |
Global flags
Most top-level flags work on most commands. Full list:
-f, --format <name>– output format (see Concepts: Output).--preset <name>– rendering preset (blog,notes,social,rag,dataset,report).--template <string>– Markdoc-style custom template.--mode <mode>– navigation mode (direct,read,navigate,interact,agent,screenshot).--sense <feature>– repeatable; request a sensor on an audio/video source.--dry-run– when set on mutating commands, preview without executing.--policy <path>– load a.pluckpolicy.yaml.--signing-key <pem>– Ed25519 private-key PEM for receipt signing.-o, --output <path>– write to file instead of stdout.--json– force JSON output (shorthand for--format json).--timeout <ms>– per-call timeout.-v, --verbose– trace-level logging.-q, --quiet– suppress non-error output.
Exit codes
The CLI uses a stable exit-code convention so scripts can branch reliably:
| Code | Meaning |
|---|---|
0 | Success. |
1 | Generic failure (anything that doesn't match a more specific code). |
2 | User error (bad flag, unrecognised URI, missing input). |
3 | Policy denied the action (POLICY_DENIED). |
4 | Receipt verification failed. |
5 | Pipeline phase error (CONNECTION_ERROR, EXTRACTION_ERROR, etc.). |
130 | Terminated by SIGINT. |
What's next
- Concepts: Connect – the phase mental model every CLI command builds on.
- Reference: Connectors – full URI-scheme table.
- Reference: API – REST API surface for remote agents.
- MCP-First Pipeline – 9 MCP tools that mirror the CLI surface.