Command line

Published baseline: v0.10.3.

This page describes the current source command tree, checked by the production parser without dispatch. The published v0.10.3 baseline includes the native API, guided calibration, command migrations below, S151's visible Doctor --timings, nested readiness timings and live elapsed diagnostics, and S161's interactive CLI input correction. Historical v0.10.0 retains the hidden completion-only timing option. Hidden test controls are excluded. clap's generated help and version controls remain available but are not repeated in every table.

In the tables, open means the parser accepts a value whose grammar is explained in the Meaning column. none means clap declares no default; the application may still apply the fallback described in Meaning. all means every build carries the option, while net means a maintainer build with the optional network feature carries it.

Running fragcap with no command lists registered targets and points at --help.

Retired command migration

Older releases and their preserved changelog pages may refer to command forms that the current CLI no longer accepts. Use these replacements with the published v0.10.3 command surface:

Historical pages remain searchable as release records. This page is the source of truth for commands accepted by the current binary.

Global options

These options propagate to every command.

Capture

capture

Capture a stored target or a directly named running process. Exactly one target input is required: positional SELECTOR, --target, --id, or --process. A selector is an exact handle, a case-insensitive exact name, or a 1-based row number from targets list.

fragcap capture 1 --out capture.fcapng
fragcap capture --target sample-target --duration 30s --out capture.fcapng
fragcap capture --process sample.exe --out capture.fcapng

--roles is enforced. --direction in and --direction out are recorded and reported, but v0.10.3 still writes both directions.

Sink specifications

The grammar is <destination>[,<key>=<value>]....

Accepted sink schemes: file, pcapng, jsonl, pipe, fifo, unix, tcp

Accepted sink modifiers: format, payload, rotate-size, rotate-duration, queue, timeout

format accepts pcapng or jsonl; payload accepts true or false. rotate-size and rotate-duration apply only to file destinations and are mutually exclusive. queue and timeout apply only to streaming destinations; their runtime fallbacks are 1024 records and 5 seconds. Streaming destinations cannot use rotation modifiers. Example:

fragcap capture 1 --sink "tcp://127.0.0.1:9000,format=jsonl,payload=false,queue=2048,timeout=10s"

deep-capture

Run Capture with explicit, target-scoped local proxy inspection. Exactly one stored-target input is required: positional SELECTOR, --target, or --id. The current implementation requires a managed launch, one exact complete-plan authorization, and compatible launch facts.

fragcap deep-capture sample-target --launch --har --key-log

Deep Capture hides and rejects the former --trust-ca and --yes inputs for one release. The migration error points to the complete interactive plan or --authorize-stdin. Other commands retain their separately scoped --yes confirmations.

Authorization plan and prompt writes must succeed before input is read. Interactive approval requires a complete LF-terminated line, and effective deadlines are bound at exact millisecond precision. The prepared CA must remain within its displayed validity period. Stored target authority is checked immediately after approval, then the facade independently resolves and compares the exact profile, executable paths, platform root, dispatch, and managed launch before endpoint selection. Before constructing a new plan, a bounded read-only inspection refuses any pending prior-session recovery and directs the operator to fragcap doctor --fix; the new plan never authorizes effects against an older session.

Read Output formats and session bundles for artifact authority, sensitivity, omission, correlation, retention, and cleanup. See Deep Capture compatibility for certificate-pinning, QUIC, and launch limits.

calibrate

Guide one target through a bounded sequence of current Deep Capture reachability and protocol attempts. Stored targets retain precedence. On a clean stored miss, an exact installed Steam application identifier or Unicode-aware case-insensitive display name can produce one complete registration plan. The plan exposes and binds the complete candidate, conserved discovery account and warnings, and effective store before confirmation. Interactive registration defaults to no; structured registration requires the exact emitted target-registration-v1 identifier through --authorize-stdin. Discovery is repeated before the shared single-target registration operation runs. When an exact Steam target has no authored client, appinfo's executable is labeled a launch hint. Interactive setup can confirm a separate cold Steam launch and observe descendant socket owners; a unique complete observation proposes a client under a separate steam-client-setup-v1 plan. --client-executable EXE instead records an explicit operator declaration, including in structured workflows, without claiming observed ownership. No evidence, ambiguity, interruption, or decline changes no target row. The authoring plan revalidates discovery and the full stored row before conditional update. Setup exits after authoring; close the title and Steam normally before a new cold reachability attempt. A non-Steam stored target with two or more client-only launch entries instead requires one stable executable candidate and a separate stored-client-selection-v1 confirmation before its complete row can be narrowed to one authored client. Steam targets and ordered publisher chains never enter that rewrite path. Registration, topology setup, and every later Deep Capture attempt remain separate authorizations.

For a target with authoritative topology, the command freshly reads the process image inventory and retained compatibility facts before every proposed action. Repeatable --protocol values request measurements and do not constitute evidence. Missing route evidence selects reachability first. After each separately authorized session, eligible final-client observations may add concrete candidates, but only a fresh current positive fact permits the next useful case. One workflow runs reachability at most once and each concrete protocol at most once, for a maximum of fourteen durable attempt ordinals. A decline, invalid input, interruption, failure, partial result, warm transition, limitation, target change, or repeated case stops before later effects and checkpoints current coverage. A warm target starts no session unless --restart-warm explicitly selects the existing operator-owned close-and-retry workflow.

Fresh calibration creates a target-bound workflow before its first attempt. Resume it explicitly with --resume <WORKFLOW_ID> from the same effective local store. Resume revalidates the complete target snapshot and rebuilds current process, fact, proposal, recovery, bundle, plan, and confirmation authority. It never reuses a prior plan or response. A row left in flight first becomes an effect-free interruption pause. --pause-for can record login, EULA, update, anti-cheat, gameplay, shutdown, or interruption work without entering the session executor. A pause records operator intent, not proof or compatibility evidence. Generated commands carry the effective local-store path as one PowerShell-quoted argument. If target discovery, Steam executable metadata, or an eligible stored non-Steam client declaration is ambiguous, calibration.choice_required lists stable content-derived candidate identities. Repeat the command with one exact --candidate; list positions are never accepted. The selection still passes its separate complete plan and fresh post-confirmation checks.

A failed session prints the earliest known causal stage, observed target packet retention, proxy accept count when the native cleanup report supplies it, exact fact writes, and the workflow pause. Artifact creation is separate from successful acquisition. --resume preserves a failed attempt's history and does not rerun the same exact case; correct the cause and start a fresh workflow when another attempt is needed.

Advanced fresh workflows may assert --launch-case, select --routing-strategy, and select --proxy-family. The values become immutable workflow intent and appear in guidance. A launch assertion must equal the current inferred cold topology, and unimplemented routing strategies remain pre-effect refusals. Resume cannot change candidate or exact-case intent.

fragcap calibrate sample-target
fragcap calibrate sample-target --client-executable sample.exe
fragcap calibrate "Sample Target" --candidate candidate-v1:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
fragcap calibrate --id 42 --protocol https
fragcap calibrate --id 42 --launch-case direct-exe-cold --routing-strategy child-environment --proxy-family ipv6
fragcap calibrate --resume 17 --local-db C:\Users\you\local.db
fragcap calibrate --resume 17 --pause-for login --local-db C:\Users\you\local.db

calibrate registers at most one exactly selected, explicitly confirmed discovery candidate through the shared target operation. Its durable checkpoint stores target identity, candidate intent, coverage projection, bounded ordinal, lifecycle, and pause state only. It stores no authorization, secret, trust state, endpoint, effect obligation, or compatibility claim. A request, an observation, and a current exact compatibility fact remain separate. Ambiguous, invalid, and unavailable proposals report typed limitations before effects and do not invent authority.

Guided calibration implementation acceptance is checked by the versioned thirteen-criterion registry in integration/guided-calibration-acceptance-v1.json and the ordinary Linux and Windows CI suites. S147 did not run a real game or demonstrate live compatibility. Optional real-game validation belongs to the operator and may be performed only against an already published release.

replay

Accept a capture path and trailing arguments, then report that replay is not yet implemented.

fragcap replay capture.fcapng

Targets

The local target store resolves from an explicit local-store option, then FRAGCAP_LOCAL_DB, then %APPDATA%\fragcap\local.db. The final location is a managed fallback, so a --db or --local-db option is never required merely to use the ordinary per-user store.

targets

With no subcommand, discover and register newly installed titles, then print the numbered target listing.

fragcap targets

targets add

Register a target. Positional NAME is optional when --steam supplies the installed title name.

fragcap targets add "Sample Game" --exe sample.exe --socket-holder yes
fragcap targets add --steam 620

targets list

Discover and register newly installed titles, then list row number, handle, readiness, and known technologies.

targets show

Show one target selected by positional SELECTOR or --id, including local Deep Capture compatibility evidence.

fragcap targets show sample-target

targets discover

Read installed-game candidates from Steam and known roots without registering the candidates. Detailed output reports whether each candidate is eligible for automatic registration and why. --summary emits aggregate counts only and is safe to retain as validation evidence without publishing local inventory.

targets reconcile

Preview conservative cleanup of historical tool-owned discovery residue. The default is non-mutating. --yes rebuilds the preview and atomically removes only exact rows whose complete stored value is unchanged; authored, anchored, ambiguous, or incompletely inventoried rows remain.

fragcap targets reconcile
fragcap targets reconcile --yes

targets scan

Treat positional DIR as one game location. With --catalog-db, attach technology evidence. Discovered candidates are registered idempotently in the resolved local store.

fragcap targets scan "C:\Games\Sample Game"

targets remove

Remove one target selected by positional SELECTOR or --id.

targets export

Write all registered targets, or positional SELECTOR or --id, as a JSON array to standard output.

fragcap targets export

targets import

Merge the target-entry JSON array at positional FILE by stable identifier.

fragcap targets import targets.json

Environment

technologies

Detect engine, anti-cheat, and DRM signatures in an install directory.

fragcap technologies --path "C:\Games\Sample Game"

steam

Group Steam-specific inspection commands.

steam list

List installed Steam titles. Register one with targets add --steam <app_id>.

fragcap steam list

Human output contains no tab separators. It uses an aligned APP ID, NAME, STATE, and TARGET table when every complete row fits the selected 40-through-80 display-column width, then switches the entire result to labeled vertical records when a long or localized value would not fit. Values are never truncated, and positioned, registered without a current listing position, and unregistered titles remain distinct. Use global --json for the unchanged JSON Lines machine interface.

doctor

Report environment readiness. The default is read-only; --fix offers only the remediations already named by the report.

Native Deep Capture residue is shown under a stable native residue label with plain-language ownership, readiness, and review guidance. Long session and resource identities wrap without truncation, and terminals use an aligned or compact layout from 40 through 80 display columns. With global --json, each native residue check retains its existing machine name and adds a native_resource object containing session_id, resource_id, kind, state, health, ownership_authority, and recovery_eligible. Read-only Doctor never performs cleanup; exact eligible records are reviewed and confirmed through fragcap doctor --fix.

fragcap doctor

extcap

Serve Wireshark's extcap protocol. Query flags print declarations to standard output; capture streams pcapng to the analyzer-provided FIFO.

extcap install

Register fragcap in Wireshark's extcap directory. With no scope flag, use the per-user directory.

fragcap extcap install --user

extcap uninstall

Remove the corresponding extcap registration. Scope flags have the same precedence as extcap install.

Data

bundle

Group explicit lifecycle operations for completed Deep Capture bundles.

bundle cleanup

Delete only artifacts that the completed bundle manifest declares sensitive. The original journal records each intent and result so interrupted cleanup can resume without broad directory deletion.

fragcap bundle cleanup .\fragcap-session --yes

bundle export

Create a separate share copy containing ordinary artifacts and a complete sharing manifest. The source bundle is never modified.

fragcap bundle export .\fragcap-session --out .\fragcap-session-share

fresh-start

Preview or irreversibly remove canonical fragcap user data. Preview is read-only and emits an inventory identifier. Execution requires both --confirm with that exact unchanged identifier and --yes. Current-user scope covers only %APPDATA%\fragcap and %LOCALAPPDATA%\fragcap. All-users scope requires an elevated Administrator session and a report path. It enumerates Windows profiles through the operating system profile authority rather than searching the filesystem. Deep Capture evidence in another profile remains for current-user recovery under that profile's Windows trust identity, so such an all-users result is partial until that recovery is complete.

fragcap fresh-start --scope current-user --preview
fragcap fresh-start --scope current-user --confirm <inventory-id> --yes --report .\fresh-start-report.json

Deep Capture session evidence is removed only after Doctor's exact recovery authority reaches safe terminal states. Custom paths, Npcap, Wireshark configuration, and independently managed extcap registrations are excluded. A redirection or recovery failure remains in the report and makes the result partial.

Catalog store options resolve from explicit --db, then FRAGCAP_CATALOG_DB, then %APPDATA%\fragcap\catalog.db. The managed path is the ordinary fallback, not a required argument.

catalog

Group commands for the shipped, disposable catalog store.

catalog import

Load positional SEED, a schema-conformant local JSON export, transactionally.

fragcap catalog import catalog.json

catalog export

Write the catalog store as schema-conformant JSON to standard output.

catalog seed

Fill one repeatable --tier or every tier with an available source. --from is the hermetic local source. --steam and --pcgamingwiki exist only in an optional network-capable maintainer build.

fragcap catalog seed --tier signature
fragcap catalog seed --tier catalog --from catalog.json

schema

Group commands for the embedded master JSON schema.

schema validate

Validate positional FILE and report every structural violation in one pass.

fragcap schema validate targets.json

schema print

Write the embedded master schema to standard output.

Output routing

--json changes presentation, not the ownership of streams. Structured command results, such as target, Steam, doctor, catalog, and schema results, go to standard output. Capture and Deep Capture lifecycle events go to standard error so they cannot contaminate capture bytes. Packet bytes and packet JSON Lines go only to the configured --out, --sink, or extcap FIFO destination. Warnings and errors are diagnostics on standard error.

--quiet suppresses progress but retains authoritative terminal results, warnings, and errors. --silent suppresses optional progress, completion summaries, and warnings; errors and configured sinks remain active. Neither flag hides required complete authorization plans or turns consent into approval. A consumer must parse documented result and lifecycle streams separately; there is no combined JSON stream.