CLI reference
All commands are accessed via the filedge entry point.
filedge inspect
Sample a file and generate a columns: block for pipeline.yaml.
| 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 preview
Display rows of a file as a formatted table.
| 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.
| 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.
| 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.
| Option | Env var | Default | Description |
|---|---|---|---|
--dir |
— | required | Watched directory path (local or cloud URI) |
--config |
— | required | Path to pipeline.yaml |
--audit-db-url |
FILEDGE_AUDIT_DB_URL |
required | Audit database URL |
--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 |
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.
| 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>
| 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 |
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.
| Option | Env var | Default | Description |
|---|---|---|---|
--audit-db-url |
FILEDGE_AUDIT_DB_URL |
required | Audit database URL |
--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
Exit codes: 0 on success, 1 on error.
filedge completion
Print shell completion scripts for zsh or bash.