= CLI Reference
:toc: macro
:toc-title: Contents
:toclevels: 3
:sectnums:
:icons: font
:source-highlighter: rouge

Complete command-line interface reference for generated pipelines.

toc::[]

== Overview

Generated pipelines provide a comprehensive CLI with subcommands:

[source]
----
project-name [OPTIONS] <COMMAND>

Commands:
  run          Run the data processing pipeline
  validate     Validate data without processing
  config       Manage configuration
  checksum     Checksum operations
  completions  Generate shell completions
  manpage      Generate man page
  help         Print help information
----

== Global Options

These options are available for all commands:

=== Logging

[cols="2,3,1"]
|===
|Option |Description |Default

|`-v, --verbose`
|Increase verbosity (-v, -vv, -vvv, -vvvv)
|warn

|`-q, --quiet`
|Suppress non-error output
|false

|`--log-format <FORMAT>`
|Output format: pretty, compact, json, full
|pretty

|`--log-file <PATH>`
|Write logs to file
|stderr

|`--log-timestamps`
|Include timestamps in logs
|true
|===

=== Configuration

[cols="2,3,1"]
|===
|Option |Description |Default

|`-c, --config <PATH>`
|Configuration file path
|~/.config/project/config.toml

|`--no-env`
|Ignore environment variable overrides
|false

|`--env-file <PATH>`
|Load environment from file
|none
|===

=== Debug

[cols="2,3,1"]
|===
|Option |Description |Default

|`--debug`
|Enable debug mode with diagnostics
|false

|`--print-config`
|Print effective configuration and exit
|false

|`--no-color`
|Disable colored output
|false

|`--no-progress`
|Disable progress indicators
|false
|===

== run Command

Execute the data processing pipeline.

=== Synopsis

[source,bash]
----
project-name run [OPTIONS] --input <PATH> --output <PATH>
----

=== Input Options

[cols="2,3,1"]
|===
|Option |Description |Default

|`-i, --input <PATH>`
|Input path (file or directory, repeatable)
|required

|`--input-format <FORMAT>`
|Input format: auto, json, jsonl, csv, tsv, parquet, arrow
|auto

|`--input-encoding <ENCODING>`
|Text encoding
|utf-8

|`--input-glob <PATTERN>`
|Filter input files by glob pattern
|none

|`-R, --recursive`
|Process directories recursively
|true

|`--max-depth <N>`
|Maximum recursion depth
|unlimited

|`--follow-symlinks`
|Follow symbolic links
|false
|===

=== Output Options

[cols="2,3,1"]
|===
|Option |Description |Default

|`-o, --output <PATH>`
|Output path
|required

|`--output-format <FORMAT>`
|Output format
|auto

|`--output-encoding <ENCODING>`
|Text encoding
|utf-8

|`-f, --overwrite`
|Overwrite existing output
|false

|`-p, --create-parents`
|Create parent directories
|true

|`--preserve-metadata`
|Preserve file timestamps/permissions
|false

|`--output-mode <MODE>`
|Output file permissions (octal)
|644
|===

=== Processing Options

[cols="2,3,1"]
|===
|Option |Description |Default

|`-a, --algorithm <ALG>`
|Processing algorithm: default, fast, thorough, streaming
|default

|`-b, --batch-size <N>`
|Records per batch
|1000

|`--buffer-size <BYTES>`
|I/O buffer size
|8MB

|`--memory-limit <BYTES>`
|Memory usage limit (0 = unlimited)
|0
|===

=== Performance Options

[cols="2,3,1"]
|===
|Option |Description |Default

|`-t, --threads <N>`
|Number of worker threads
|4

|`--fast`
|Enable fast mode (reduced validation)
|false

|`--streaming`
|Enable streaming mode for large files
|false

|`--mmap`
|Use memory-mapped I/O
|false

|`--no-parallel`
|Disable parallel processing
|false
|===

=== Validation Options

[cols="2,3,1"]
|===
|Option |Description |Default

|`--validate <LEVEL>`
|Validation level: skip, quick, standard, full, paranoid
|standard

|`--strict`
|Fail on any warning
|false

|`--tolerance <RATIO>`
|Validation tolerance (0.0-1.0)
|0.01

|`--schema <PATH>`
|Schema file for validation
|none

|`--no-validate`
|Skip all validation (dangerous)
|false
|===

=== Checksum Options

[cols="2,3,1"]
|===
|Option |Description |Default

|`--checksum <ALG>`
|Checksum algorithm: none, shake256, blake3, sha3-256, xxhash
|shake256

|`--verify-checksums`
|Verify input checksums
|false

|`--generate-checksums`
|Generate output checksums
|true

|`--checksum-ext <EXT>`
|Checksum file extension
|.shake256
|===

=== Execution Control

[cols="2,3,1"]
|===
|Option |Description |Default

|`-n, --dry-run`
|Simulate without writing
|false

|`-k, --continue-on-error`
|Continue after errors
|false

|`--max-errors <N>`
|Maximum errors before abort
|10

|`--retries <N>`
|Number of retry attempts
|0

|`--retry-delay <MS>`
|Delay between retries
|1000

|`--timeout <SECS>`
|Operation timeout (0 = none)
|0
|===

=== Examples

[source,bash]
----
# Basic run
project-name run --input ./data --output ./results

# Dry run with verbose output
project-name run -n -vvv --input ./data --output ./results

# Parallel processing with strict validation
project-name run --threads 8 --validate full --strict \
  --input ./data --output ./results

# Streaming large files
project-name run --streaming --buffer-size 67108864 \
  --input ./large-data --output ./results
----

== validate Command

Validate data without processing.

=== Synopsis

[source,bash]
----
project-name validate [OPTIONS] --input <PATH>
----

=== Options

[cols="2,3,1"]
|===
|Option |Description |Default

|`-i, --input <PATH>`
|Input path(s) to validate
|required

|`--format <FORMAT>`
|Input format
|auto

|`--level <LEVEL>`
|Validation level
|standard

|`--schema <PATH>`
|Schema file
|none

|`--strict`
|Fail on warnings
|false

|`--report <PATH>`
|Output validation report
|none

|`--checksums`
|Verify checksums
|false

|`--proofs`
|Verify formal proofs
|false

|`-R, --recursive`
|Validate recursively
|false
|===

== config Command

Manage configuration.

=== Subcommands

==== config show

Display current configuration.

[source,bash]
----
project-name config show [--format toml|json|yaml] [--section <NAME>]
----

==== config validate

Validate a configuration file.

[source,bash]
----
project-name config validate [PATH]
----

==== config generate

Generate default configuration.

[source,bash]
----
project-name config generate [-o PATH] [--format toml|json|yaml] [--full]
----

==== config edit

Open configuration in editor.

[source,bash]
----
project-name config edit
----

==== config path

Show configuration file location.

[source,bash]
----
project-name config path
----

== checksum Command

Checksum operations.

=== Subcommands

==== checksum compute

Compute checksums for files.

[source,bash]
----
project-name checksum compute <PATHS...> \
  [-a blake3|shake256|sha3-256|xxhash] \
  [--format hex|base64|bsd|gnu] \
  [--write] [-R]
----

==== checksum verify

Verify checksums.

[source,bash]
----
project-name checksum verify <PATH> [-a ALGORITHM] [--strict]
----

==== checksum compare

Compare files by checksum.

[source,bash]
----
project-name checksum compare <PATH1> <PATH2> [-a ALGORITHM]
----

== completions Command

Generate shell completions.

[source,bash]
----
# Bash
project-name completions bash >> ~/.bashrc

# Zsh
project-name completions zsh > ~/.zfunc/_project-name

# Fish
project-name completions fish > ~/.config/fish/completions/project-name.fish

# PowerShell
project-name completions powershell >> $PROFILE
----

== manpage Command

Generate man page.

[source,bash]
----
# Generate man page
project-name manpage > /usr/local/share/man/man1/project-name.1

# With subcommand pages
project-name manpage --subcommands
----

== Environment Variables

All CLI options can be set via environment variables:

[cols="2,2"]
|===
|Variable |Corresponding Option

|`PROJECT_NAME_CONFIG`
|`--config`

|`PROJECT_NAME_THREADS`
|`--threads`

|`PROJECT_NAME_VALIDATION`
|`--validate`

|`PROJECT_NAME_CHECKSUM`
|`--checksum`

|`PROJECT_NAME_LOG_FORMAT`
|`--log-format`

|`PROJECT_NAME_LOG_FILE`
|`--log-file`

|`PROJECT_NAME_DEBUG`
|`--debug`

|`PROJECT_NAME_NO_PROGRESS`
|`--no-progress`

|`NO_COLOR`
|`--no-color`
|===

== Exit Codes

[cols="1,3"]
|===
|Code |Meaning

|0 |Success
|1 |General error
|2 |Configuration error
|3 |Validation error
|4 |I/O error
|5 |Pipeline error
|64 |Usage error (invalid arguments)
|===

== See Also

* link:QUICKSTART.adoc[QUICKSTART.adoc] — Getting started guide
* link:ARCHITECTURE.adoc[ARCHITECTURE.adoc] — Technical architecture
* link:HANDOVER.adoc[HANDOVER.adoc] — Complete methodology
