logwisp/doc/cli.md

Command Line Interface

LogWisp CLI options for controlling behavior without modifying configuration files.

Synopsis

logwisp [options]

General Options

--config <path>

Configuration file location.

• Default: ~/.config/logwisp/logwisp.toml
• Example: logwisp --config /etc/logwisp/production.toml

--router

Enable HTTP router mode for path-based routing.

• Default: false
• Example: logwisp --router

--version

Display version information.

--background

Run as background process.

• Example: logwisp --background

--quiet

Suppress all output (overrides logging configuration) except sinks.

• Example: logwisp --quiet

--disable-status-reporter

Disable periodic status reporting.

• Example: logwisp --disable-status-reporter

--config-auto-reload

Enable automatic configuration reloading on file changes.

• Example: logwisp --config-auto-reload --config /etc/logwisp/config.toml
• Monitors configuration file for changes
• Reloads pipelines without restart
• Preserves connections during reload

--config-save-on-exit

Save current configuration to file on exit.

• Example: logwisp --config-save-on-exit
• Useful with runtime modifications
• Requires valid config file path

Logging Options

Override configuration file settings:

--logging.output <mode>

LogWisp's operational log output.

• Values: file, stdout, stderr, both, none
• Example: logwisp --logging.output both

--logging.level <level>

Minimum log level.

• Values: debug, info, warn, error
• Example: logwisp --logging.level debug

--logging.file.directory <path>

Log directory (with file output).

• Example: logwisp --logging.file.directory /var/log/logwisp

--logging.file.name <name>

Log file name (with file output).

• Example: logwisp --logging.file.name app

--logging.file.max_size_mb <size>

Maximum log file size in MB.

• Example: logwisp --logging.file.max_size_mb 200

--logging.file.max_total_size_mb <size>

Maximum total log size in MB.

• Example: logwisp --logging.file.max_total_size_mb 2000

--logging.file.retention_hours <hours>

Log retention period in hours.

• Example: logwisp --logging.file.retention_hours 336

--logging.console.target <target>

Console output destination.

• Values: stdout, stderr, split
• Example: logwisp --logging.console.target split

--logging.console.format <format>

Console output format.

• Values: txt, json
• Example: logwisp --logging.console.format json

Pipeline Options

Configure pipelines via CLI (N = array index, 0-based):

--pipelines.N.name <name>

Pipeline name.

• Example: logwisp --pipelines.0.name myapp

--pipelines.N.sources.N.type <type>

Source type.

• Example: logwisp --pipelines.0.sources.0.type directory

--pipelines.N.sources.N.options.<key> <value>

Source options.

• Example: logwisp --pipelines.0.sources.0.options.path /var/log

--pipelines.N.filters.N.type <type>

Filter type.

• Example: logwisp --pipelines.0.filters.0.type include

--pipelines.N.filters.N.patterns <json>

Filter patterns (JSON array).

• Example: logwisp --pipelines.0.filters.0.patterns '["ERROR","WARN"]'

--pipelines.N.sinks.N.type <type>

Sink type.

• Example: logwisp --pipelines.0.sinks.0.type http

--pipelines.N.sinks.N.options.<key> <value>

Sink options.

• Example: logwisp --pipelines.0.sinks.0.options.port 8080

Examples

Basic Usage

# Default configuration
logwisp

# Specific configuration
logwisp --config /etc/logwisp/production.toml

Development

# Debug mode
logwisp --logging.output stderr --logging.level debug

# With file output
logwisp --logging.output both --logging.level debug --logging.file.directory ./debug-logs

Production

# File logging
logwisp --logging.output file --logging.file.directory /var/log/logwisp

# Background with router
logwisp --background --router --config /etc/logwisp/prod.toml

# Quiet mode for cron
logwisp --quiet --config /etc/logwisp/batch.toml

Pipeline Configuration via CLI

# Simple pipeline
logwisp --pipelines.0.name app \
        --pipelines.0.sources.0.type directory \
        --pipelines.0.sources.0.options.path /var/log/app \
        --pipelines.0.sinks.0.type http \
        --pipelines.0.sinks.0.options.port 8080

# With filters
logwisp --pipelines.0.name filtered \
        --pipelines.0.sources.0.type stdin \
        --pipelines.0.filters.0.type include \
        --pipelines.0.filters.0.patterns '["ERROR","CRITICAL"]' \
        --pipelines.0.sinks.0.type stdout

Priority Order

1. Command-line flags (highest)
2. Environment variables
3. Configuration file
4. Built-in defaults (lowest)

Exit Codes

• 0: Success
• 1: General error
• 2: Configuration file not found
• 137: SIGKILL received

Signals

• SIGINT (Ctrl+C): Graceful shutdown
• SIGTERM: Graceful shutdown
• SIGHUP: Reload configuration (when auto-reload enabled)
• SIGUSR1: Reload configuration (when auto-reload enabled)
• SIGKILL: Immediate shutdown (exit code 137)