v0.7.1 default config and documentation update, refactor
This commit is contained in:
392
doc/cli.md
392
doc/cli.md
@ -1,196 +1,260 @@
|
||||
# Command Line Interface
|
||||
|
||||
LogWisp CLI options for controlling behavior without modifying configuration files.
|
||||
LogWisp CLI reference for commands and options.
|
||||
|
||||
## Synopsis
|
||||
|
||||
```bash
|
||||
logwisp [command] [options]
|
||||
logwisp [options]
|
||||
```
|
||||
|
||||
## General Options
|
||||
## Commands
|
||||
|
||||
### `--config <path>`
|
||||
Configuration file location.
|
||||
- **Default**: `~/.config/logwisp/logwisp.toml`
|
||||
- **Example**: `logwisp --config /etc/logwisp/production.toml`
|
||||
### Main Commands
|
||||
|
||||
### `--router`
|
||||
Enable HTTP router mode for path-based routing.
|
||||
- **Default**: `false`
|
||||
- **Example**: `logwisp --router`
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `auth` | Generate authentication credentials |
|
||||
| `tls` | Generate TLS certificates |
|
||||
| `version` | Display version information |
|
||||
| `help` | Show help information |
|
||||
|
||||
### auth Command
|
||||
|
||||
Generate authentication credentials.
|
||||
|
||||
```bash
|
||||
logwisp auth [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `-u, --user` | Username | Required for password auth |
|
||||
| `-p, --password` | Password | Prompts if not provided |
|
||||
| `-b, --basic` | Generate basic auth | - |
|
||||
| `-s, --scram` | Generate SCRAM auth | - |
|
||||
| `-k, --token` | Generate bearer token | - |
|
||||
| `-l, --length` | Token length in bytes | 32 |
|
||||
|
||||
### tls Command
|
||||
|
||||
Generate TLS certificates.
|
||||
|
||||
```bash
|
||||
logwisp tls [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `-ca` | Generate CA certificate | - |
|
||||
| `-server` | Generate server certificate | - |
|
||||
| `-client` | Generate client certificate | - |
|
||||
| `-host` | Comma-separated hosts/IPs | localhost |
|
||||
| `-o` | Output file prefix | Required |
|
||||
| `-ca-cert` | CA certificate file | Required for server/client |
|
||||
| `-ca-key` | CA key file | Required for server/client |
|
||||
| `-days` | Certificate validity days | 365 |
|
||||
|
||||
### version Command
|
||||
|
||||
### `--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
|
||||
```bash
|
||||
# Default configuration
|
||||
logwisp
|
||||
|
||||
# Specific configuration
|
||||
logwisp --config /etc/logwisp/production.toml
|
||||
logwisp version
|
||||
logwisp -v
|
||||
logwisp --version
|
||||
```
|
||||
|
||||
### Development
|
||||
```bash
|
||||
# Debug mode
|
||||
logwisp --logging.output stderr --logging.level debug
|
||||
Output includes:
|
||||
- Version number
|
||||
- Build date
|
||||
- Git commit hash
|
||||
- Go version
|
||||
|
||||
# With file output
|
||||
logwisp --logging.output both --logging.level debug --logging.file.directory ./debug-logs
|
||||
## Global Options
|
||||
|
||||
### Configuration Options
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `-c, --config` | Configuration file path | `./logwisp.toml` |
|
||||
| `-b, --background` | Run as daemon | false |
|
||||
| `-q, --quiet` | Suppress console output | false |
|
||||
| `--disable-status-reporter` | Disable status logging | false |
|
||||
| `--config-auto-reload` | Enable config hot reload | false |
|
||||
|
||||
### Logging Options
|
||||
|
||||
| Flag | Description | Values |
|
||||
|------|-------------|--------|
|
||||
| `--logging.output` | Log output mode | file, stdout, stderr, split, all, none |
|
||||
| `--logging.level` | Log level | debug, info, warn, error |
|
||||
| `--logging.file.directory` | Log directory | Path |
|
||||
| `--logging.file.name` | Log filename | String |
|
||||
| `--logging.file.max_size_mb` | Max file size | Integer |
|
||||
| `--logging.file.max_total_size_mb` | Total size limit | Integer |
|
||||
| `--logging.file.retention_hours` | Retention period | Float |
|
||||
| `--logging.console.target` | Console target | stdout, stderr, split |
|
||||
| `--logging.console.format` | Output format | txt, json |
|
||||
|
||||
### Pipeline Options
|
||||
|
||||
Configure pipelines via CLI (N = array index, 0-based).
|
||||
|
||||
**Pipeline Configuration:**
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--pipelines.N.name` | Pipeline name |
|
||||
| `--pipelines.N.sources.N.type` | Source type |
|
||||
| `--pipelines.N.filters.N.type` | Filter type |
|
||||
| `--pipelines.N.sinks.N.type` | Sink type |
|
||||
|
||||
## Flag Formats
|
||||
|
||||
### Boolean Flags
|
||||
|
||||
```bash
|
||||
logwisp --quiet
|
||||
logwisp --quiet=true
|
||||
logwisp --quiet=false
|
||||
```
|
||||
|
||||
### Production
|
||||
### String Flags
|
||||
|
||||
```bash
|
||||
# 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
|
||||
logwisp --config /etc/logwisp/config.toml
|
||||
logwisp -c config.toml
|
||||
```
|
||||
|
||||
### Pipeline Configuration via CLI
|
||||
```bash
|
||||
# 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
|
||||
### Nested Configuration
|
||||
|
||||
# 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
|
||||
```bash
|
||||
logwisp --logging.level=debug
|
||||
logwisp --pipelines.0.name=myapp
|
||||
logwisp --pipelines.0.sources.0.type=stdin
|
||||
```
|
||||
|
||||
## Priority Order
|
||||
### Array Values (JSON)
|
||||
|
||||
1. **Command-line flags** (highest)
|
||||
2. **Environment variables**
|
||||
3. **Configuration file**
|
||||
4. **Built-in defaults** (lowest)
|
||||
```bash
|
||||
logwisp --pipelines.0.filters.0.patterns='["ERROR","WARN"]'
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
All flags can be set via environment:
|
||||
|
||||
```bash
|
||||
export LOGWISP_QUIET=true
|
||||
export LOGWISP_LOGGING_LEVEL=debug
|
||||
export LOGWISP_PIPELINES_0_NAME=myapp
|
||||
```
|
||||
|
||||
## Configuration Precedence
|
||||
|
||||
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
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 0 | Success |
|
||||
| 1 | General error |
|
||||
| 2 | Configuration file not found |
|
||||
| 137 | SIGKILL received |
|
||||
|
||||
## Signals
|
||||
## Signal Handling
|
||||
|
||||
- `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)
|
||||
| Signal | Action |
|
||||
|--------|--------|
|
||||
| SIGINT (Ctrl+C) | Graceful shutdown |
|
||||
| SIGTERM | Graceful shutdown |
|
||||
| SIGHUP | Reload configuration |
|
||||
| SIGUSR1 | Reload configuration |
|
||||
| SIGKILL | Immediate termination |
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### Development Mode
|
||||
|
||||
```bash
|
||||
# Verbose logging to console
|
||||
logwisp --logging.output=stderr --logging.level=debug
|
||||
|
||||
# Quick test with stdin
|
||||
logwisp --pipelines.0.sources.0.type=stdin --pipelines.0.sinks.0.type=console
|
||||
```
|
||||
|
||||
### Production Deployment
|
||||
|
||||
```bash
|
||||
# Background with file logging
|
||||
logwisp --background --config /etc/logwisp/prod.toml --logging.output=file
|
||||
|
||||
# Systemd service
|
||||
ExecStart=/usr/local/bin/logwisp --config /etc/logwisp/config.toml
|
||||
```
|
||||
|
||||
### Debugging
|
||||
|
||||
```bash
|
||||
# Check configuration
|
||||
logwisp --config test.toml --logging.level=debug --disable-status-reporter
|
||||
|
||||
# Dry run (verify config only)
|
||||
logwisp --config test.toml --quiet
|
||||
```
|
||||
|
||||
### Quick Commands
|
||||
|
||||
```bash
|
||||
# Generate admin password
|
||||
logwisp auth -u admin -b
|
||||
|
||||
# Create self-signed certs
|
||||
logwisp tls -server -host localhost -o server
|
||||
|
||||
# Check version
|
||||
logwisp version
|
||||
```
|
||||
|
||||
## Help System
|
||||
|
||||
### General Help
|
||||
|
||||
```bash
|
||||
logwisp --help
|
||||
logwisp -h
|
||||
logwisp help
|
||||
```
|
||||
|
||||
### Command Help
|
||||
|
||||
```bash
|
||||
logwisp auth --help
|
||||
logwisp tls --help
|
||||
logwisp help auth
|
||||
```
|
||||
|
||||
## Special Flags
|
||||
|
||||
### Internal Flags
|
||||
|
||||
These flags are for internal use:
|
||||
- `--background-daemon`: Child process indicator
|
||||
- `--config-save-on-exit`: Save config on shutdown
|
||||
|
||||
### Hidden Behaviors
|
||||
|
||||
- SIGHUP ignored by default (nohup behavior)
|
||||
- Automatic panic recovery in pipelines
|
||||
- Resource cleanup on shutdown
|
||||
Reference in New Issue
Block a user