CLI reference

All commands are accessed via the filedge entry point.

filedge --help
filedge <command> --help

`filedge inspect`

Sample a file and generate a columns: block for pipeline.yaml.

filedge inspect <file> [options]

Option	Default	Description
`<file>`	required	File to inspect (local path or cloud URI)
`--format`	auto from extension	File format: `csv`, `ndjson`, or `parquet`
`--sample-rows`	1000	Number of rows to sample
`--output`	stdout	Write YAML block to this file instead of stdout
`--encoding`	`utf-8`	File encoding for text formats

Exit codes: 0 on success, 1 on error.

See the Inspect guide for full details.

`filedge author`

Launch the local Authoring UI: review the inferred schema, choose write mode, connector, and field encryption, validate, and generate a Pipeline Folder. Requires the authoring extra (uv sync --extra authoring).

Pass a <sample-file> to author from scratch, or --pipeline <folder> to re-open an existing Pipeline Folder and revise its config in place. With neither argument, the UI opens a browse-and-pick screen of registered Pipelines when a Pipeline Registry exists in the workspace, and otherwise asks for a sample file or --pipeline.

filedge author <sample-file> [options]
filedge author --pipeline <folder> [options]
filedge author [--workspace <dir>]            # browse the Pipeline Registry

Option	Default	Description
`<sample-file>`	—	Sample file to author from (local path or cloud URI). Mutually exclusive with `--pipeline`
`--pipeline`	—	Re-author an existing Pipeline Folder (workspace-relative path). Mutually exclusive with `<sample-file>`
`--format`	auto from extension	File format: `csv`, `ndjson`, `parquet`, `excel`, or `fixed_width`
`--sample-rows`	1000	Number of rows to sample for schema inference
`--dest-table`	sample file stem	Destination table name
`--out`	from `--dest-table`	Pipeline Folder id/name override
`--workspace`	`.`	Workspace root for the Pipeline Folder and Pipeline Registry
`--encoding`	auto	File encoding override
`--sheet`	first sheet	Excel sheet name or 0-based index (excel format only)

Exit codes: 0 on success, 1 if the authoring extra is not installed, 2 on error (bad file path, unrecognised format, both <sample-file> and --pipeline given, or neither with no Registry to browse).

See the Author guide for full details.

`filedge preview`

Display rows of a file as a formatted table.

filedge preview <file> [options]

Option	Default	Description
`<file>`	required	File to preview (local path or cloud URI)
`--format`	auto from extension	File format: `csv`, `ndjson`, or `parquet`
`--rows`	10	Number of rows to display
`--start-row`	1	First row to display (1-indexed)
`--encoding`	`utf-8`	File encoding for text formats

Exit codes: 0 on success, 2 on error (bad file path, unrecognised format).

See the Preview guide for full details.

`filedge validate`

Dry-run a file against a pipeline.yaml config. No data is written.

filedge validate <file> --config <path> [options]

Option	Default	Description
`<file>`	required	File to validate (local path or cloud URI)
`--config`	required	Path to `pipeline.yaml`
`--format`	auto from extension	File format: `csv`, `ndjson`, or `parquet`
`--sample-rows`	all rows	Validate only the first N rows
`--json`	off	Emit JSON to stdout in addition to text summary
`--encoding`	config value	Override file encoding from `pipeline.yaml`

Exit codes: 0 clean, 1 failures found, 2 error (bad file path, bad config).

See the Validate guide for full details.

`filedge compact`

Merge small NDJSON files into fewer, larger files before ingestion.

filedge compact --watched-dir <path> --output <path> [options]

Option	Default	Description
`--watched-dir`	required	Source prefix containing small files
`--output`	required	Output prefix for compacted files
`--max-files`	1000	Max input files per output batch
`--compress`	off	Gzip-compress output files (`.ndjson.gz`)
`--delete-source`	off	Delete source files after each batch commits

Exit codes: 0 on success, 1 on error.

See the Compact guide for full details.

`filedge run`

Ingest files from a watched directory with retry-safe commits and a full audit trail.

filedge run --dir <path> --config <path> --audit-db-url <url> [--progress|--no-progress]
filedge run --pipeline <id> [--workspace <path>] [--progress|--no-progress]

Option	Env var	Default	Description
`--pipeline`	—	—	Resolve `--dir`/`--config`/`--audit-db-url` from this Pipeline Registry id. Mutually exclusive with those three flags
`--workspace`	—	`.`	Workspace root holding `pipeline-registry.yaml` (used with `--pipeline`)
`--dir`	—	required*	Watched directory path (local or cloud URI). Mutually exclusive with `--pipeline`
`--config`	—	required*	Path to `pipeline.yaml`. Mutually exclusive with `--pipeline`
`--audit-db-url`	`FILEDGE_AUDIT_DB_URL`	required*	Audit database URL. Mutually exclusive with `--pipeline`
`--progress / --no-progress`	—	auto	Show live progress bars; defaults to on for interactive terminals
`--json`	—	off	Write the Run summary as JSON
`--log-format`	—	auto	`text` on a TTY, `json` otherwise
`--log-level`	—	`INFO`	Log level
`--otel-traces / --no-otel-traces`	`FILEDGE_OTEL_TRACES`	off	Enable OpenTelemetry tracing
`--otel-logs / --no-otel-logs`	`FILEDGE_OTEL_LOGS`	off	Enable the OpenTelemetry log bridge

* Provide either --pipeline or all three of --dir/--config/--audit-db-url, not both.

Exit codes: 0 on success, 1 on error.

See the Run guide for full details.

`filedge healthcheck`

Probe the Audit DB and destination connector without writing data.

filedge healthcheck --config <path> --audit-db-url <url> [--json]

Option	Env var	Default	Description
`--config`	—	required	Path to `pipeline.yaml`
`--audit-db-url`	`FILEDGE_AUDIT_DB_URL`	required	Audit database URL
`--json`	—	off	Write one machine-readable health object

Exit codes: 0 when all checks pass, 1 when any check fails.

See the Healthcheck guide for full details.

`filedge requeue`

Move terminal FAILED files back to PENDING so the next run can retry them.

filedge requeue <filename> --audit-db-url <url>
filedge requeue --all-terminal-failed --yes --audit-db-url <url>
filedge requeue <filename> --pipeline <id> [--workspace <path>]

Option	Env var	Default	Description
`<filename>`	—	optional	Failed filename to requeue
`--hash`	—	optional	Content hash to disambiguate duplicate filenames
`--all-terminal-failed`	—	off	Select every terminal failed file
`--dry-run`	—	off	List bulk requeue candidates without changing state
`--yes`	—	off	Confirm bulk requeue
`--retry-cap`	—	`3`	Retry cap used to identify terminal failures
`--audit-db-url`	`FILEDGE_AUDIT_DB_URL`	required	Audit database URL. Mutually exclusive with `--pipeline`
`--pipeline`	—	—	Resolve the Audit DB from this Pipeline Registry id instead of `--audit-db-url`
`--workspace`	—	`.`	Workspace root holding `pipeline-registry.yaml` (used with `--pipeline`)

Exit codes: 0 on success, 1 on error or missing bulk confirmation.

See the Requeue failed files guide for full details.

`filedge status`

Show a summary of file states in the audit database.

filedge status --audit-db-url <url> [--json]
filedge status --pipeline <id> [--workspace <path>] [--json]
filedge status --all [--workspace <path>] [--json]

Option	Env var	Default	Description
`--audit-db-url`	`FILEDGE_AUDIT_DB_URL`	required	Audit database URL. Mutually exclusive with `--pipeline` and `--all`
`--pipeline`	—	—	Resolve the Audit DB from this Pipeline Registry id instead of `--audit-db-url`. Mutually exclusive with `--all`
`--all`	—	off	Fan out across every Pipeline in the Registry, summarizing each Audit DB independently. Mutually exclusive with `--pipeline` and `--audit-db-url`
`--workspace`	—	`.`	Workspace root holding `pipeline-registry.yaml` (used with `--pipeline` or `--all`)
`--json`	—	off	Output as JSON

Example output:

PENDING:    0
PROCESSING: 0
COMMITTED:  47
FAILED:     1

Recent failures:
  bad_data.csv: cannot coerce 'n/a' to float

With --all, the same summary is printed once per Pipeline, each block keyed by its Registry id. Each Audit DB is opened on its own (never joined — one Audit DB maps to exactly one Pipeline). A Pipeline whose Audit DB cannot be resolved or opened prints inline as <id>: ERROR: <reason> and the others still report:

alpha:
  PENDING:    0
  PROCESSING: 0
  COMMITTED:  47
  FAILED:     0

beta: ERROR: Environment variable 'BETA_DB' is not set

With --all --json, the output is a JSON array with one object per Pipeline: {"pipeline": "<id>", ...summary} for healthy entries and {"pipeline": "<id>", "error": "<reason>"} for errored ones.

Exit codes: 0 on success, 1 on error (including a missing or malformed Registry, or --all combined with --pipeline / --audit-db-url).

`filedge lineage`

Show the full audit record and source-manifest metadata for one file.

filedge lineage <content-hash-or-filename> --audit-db-url <url> [--json]
filedge lineage <content-hash-or-filename> --pipeline <id> [--workspace <path>] [--json]

Option	Env var	Default	Description
`<content-hash-or-filename>`	—	required	Exact content hash or filename to inspect
`--audit-db-url`	`FILEDGE_AUDIT_DB_URL`	required	Audit database URL. Mutually exclusive with `--pipeline`
`--pipeline`	—	—	Resolve the Audit DB from this Pipeline Registry id instead of `--audit-db-url`
`--workspace`	—	`.`	Workspace root holding `pipeline-registry.yaml` (used with `--pipeline`)
`--json`	—	off	Emit machine-readable JSON
`--dest-table`	—	none	Destination table name to include in output

When a filename maps to multiple content hashes, the command prints the matching hashes and exits non-zero. Re-run with one of those hashes to inspect a specific file.

Exit codes: 0 on success, 1 when no file matches, 2 when a filename is ambiguous.

See the Source manifests guide for full details.

`filedge export-audit`

Generate a self-contained, read-only HTML audit site from the Audit DB.

filedge export-audit --audit-db-url <url> --output <path> [options]
filedge export-audit --pipeline <id> [--workspace <path>] [options]

Option	Env var	Default	Description
`--audit-db-url`	`FILEDGE_AUDIT_DB_URL`	required	Audit database URL. Mutually exclusive with `--pipeline`
`--output`	—	required	Output path for the generated `index.html`. Mutually exclusive with `--pipeline`
`--pipeline`	—	—	Resolve both the Audit DB and the Audit Export destination from this Pipeline Registry id instead of `--audit-db-url`/`--output`
`--workspace`	—	`.`	Workspace root holding `pipeline-registry.yaml` (used with `--pipeline`)
`--title`	—	none	Pipeline label shown in the site header
`--dest-table`	—	none	Destination table name for lineage SQL snippets

Exit codes: 0 on success, 1 on error.

See the Audit Export guide for full details.

`filedge completion`

Print shell completion scripts for zsh or bash.

filedge completion [--shell zsh|bash]

`filedge-fetch`

The Reference Fetcher — a separate entry point, not a filedge subcommand. It is an external companion to filedge run (ADR-0018): it pulls one API Source described in a Sources Config and lands complete NDJSON Files (each with a Source Manifest sidecar) in the Watched Directory, where filedge run ingests them. It never Commits to a Destination. Supported source types include github, generic HTTP-style sources, and SEC EDGAR companyConcept sources declared as type: edgar.

filedge-fetch --config <sources.yaml> --source <name> [--dry-run]

Option	Default	Description
`--config`	required	Path to the Sources Config (`sources.yaml`)
`--source`	required	Name of the API Source within the Sources Config to fetch
`--dry-run`	off	Report the cursor window and target File without fetching

Exit codes: 0 on success (including a clean no-op when there are no new records), 1 on error (bad config, unreachable/rate-limited API, or a held Fetch Lock).

See the API Sources guide for the full Sources Config and the fetch → ingest workflow.

`filedge-materialize`

The Reference Queue Materializer — a separate entry point, not a filedge subcommand. It is an external companion to filedge run (ADR-0007, ADR-0018): it consumes one Kafka Queue Source described in a Sources Config and lands complete NDJSON Files (each with a Source Manifest carrying Offset Range Metadata) in the Watched Directory, where filedge run ingests them. It never Commits to a Destination.

Requires the kafka extra (pip install filedge[kafka]).

filedge-materialize --config <sources.yaml> --source <name> [--dry-run]

Option	Default	Description
`--config`	required	Path to the Sources Config (`sources.yaml`)
`--source`	required	Name of the kafka Queue Source within the Sources Config
`--dry-run`	off	Report the topic and target Watched Directory without consuming

The Trigger Mode (drain default, or continuous) and batch boundary (batch_size / batch_timeout_seconds) are set per source in the Sources Config.

Exit codes: 0 on success (including a clean no-op when there are no new records), 1 on error (bad config, unreachable brokers, a decode failure, or a held Fetch Lock).

See the Queue Sources guide for the full Sources Config and the materialize → ingest workflow.