Module cli 

CLI utilities for Asupersync tools.

This module provides a comprehensive framework for building CLI tools that are both human-friendly and machine-readable. Key features:

• Dual-mode output: Automatic JSON/human output based on environment
• Structured errors: RFC 9457-style errors with context and suggestions
• Semantic exit codes: Machine-parseable exit codes for automation
• Progress reporting: Streaming progress with cancellation support
• Signal handling: Graceful shutdown with cancellation tokens
• Shell completions: Generation for bash, zsh, fish, PowerShell, elvish

Quick Start

use asupersync::cli::{Output, OutputFormat, CliError, ExitCode};

// Auto-detect output format (JSON in CI/pipes, human in terminal)
let format = OutputFormat::auto_detect();
let mut output = Output::new(format);

// Write structured output
output.write(&my_data)?;

// Handle errors with context
let error = CliError::new("config_error", "Invalid configuration")
    .detail("The 'timeout' field must be a positive integer")
    .suggestion("Set timeout to a value like 30 or 60")
    .context("field", "timeout")
    .exit_code(ExitCode::USER_ERROR);

Output Format Detection

The output format is automatically detected based on:

1. ASUPERSYNC_OUTPUT_FORMAT environment variable
2. CI environment variable (forces JSON)
3. TTY detection (JSON for pipes, human for terminals)

Color Support

Colors are automatically enabled for terminals and respect:

• NO_COLOR environment variable (disables colors)
• CLICOLOR_FORCE environment variable (forces colors)

Exit Codes

Standard exit codes for automation:

• 0: Success
• 1: User error (bad input)
• 2: Runtime error
• 3: Internal error (bug)
• 4: Cancelled
• 5: Partial success
• 10-13: Application-specific (test failure, oracle violation, etc.)

Re-exports

pub use args::COMMON_ARGS_HELP;

pub use args::CommonArgs;

pub use args::parse_color_choice;

pub use args::parse_output_format;

pub use completion::Completable;

pub use completion::CompletionItem;

pub use completion::Shell;

pub use completion::generate_completions;

pub use error::CliError;

pub use error::errors;

pub use exit::ExitCode;

pub use output::ColorChoice;

pub use output::Output;

pub use output::OutputFormat;

pub use output::Outputtable;

pub use progress::ProgressEvent;

pub use progress::ProgressKind;

pub use progress::ProgressReporter;

pub use signal::CancellationToken;

pub use signal::Signal;

pub use signal::SignalHandler;

Modules

args

Standard CLI argument handling.

completion

Shell completion generation for CLI tools.

error

Structured error messages for CLI tools.

exit

Semantic exit codes for Asupersync CLI tools.

output

Output formatting for CLI tools.

prelude

Prelude for convenient imports.

progress

Progress reporting for CLI tools.

signal

Signal handling for CLI tools.