# CLI Reference

Complete command-line interface documentation for SRX.

---

## Overview

SRX provides a simple and intuitive command-line interface with three main commands:

| Command | Description |
|---------|-------------|
| `pack` | Create an encrypted archive |
| `unpack` | Extract an archive |
| `info` | Display archive information |

---

## Global Options

These options apply to all commands:

| Option | Description |
|--------|-------------|
| `-h, --help` | Show help message |
| `-V, --version` | Show version information |
| `-v, --verbose` | Enable verbose output |

---

## `srx pack`

Create an encrypted archive from a file.

### Usage

```bash
srx pack <INPUT> <OUTPUT> -p <PASSWORD> [OPTIONS]
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `<INPUT>` | Yes | Path to the input file |
| `<OUTPUT>` | Yes | Path for the output archive (`.srx` extension recommended) |

### Options

| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--password` | `-p` | (required) | Encryption password |
| `--algo` | `-a` | `zstd` | Compression algorithm |
| `--level` | `-l` | `3` | Compression level (0-22) |
| `--chunk-size` | `-c` | `262144` | Chunk size in bytes |
| `--verbose` | `-v` | off | Enable verbose output |

### Compression Algorithms

| Value | Description | Speed | Ratio |
|-------|-------------|-------|-------|
| `zstd` | Zstandard compression (default) | Fast | Good |
| `lz4` | LZ4 compression | Very Fast | Moderate |
| `none` | No compression | Instant | 1:1 |

### Compression Levels

Valid for `zstd` algorithm:

| Level | Speed | Ratio | Use Case |
|-------|-------|-------|----------|
| `0-3` | Fast | Moderate | Default, good balance |
| `4-9` | Medium | Good | General purpose |
| `10-19` | Slow | Better | Archival |
| `20-22` | Very Slow | Best | Maximum compression |

> **Note:** Levels above 19 may require significant memory during compression.

### Examples

#### Basic Usage

```bash
# Create archive with default settings
srx pack document.pdf archive.srx -p "my_password"
```

#### Maximum Compression

```bash
# Best compression ratio (slower)
srx pack large_file.tar large_file.srx -p "secret" -l 19
```

#### Fast Compression

```bash
# LZ4 for speed-critical applications
srx pack logs.txt logs.srx -p "key" -a lz4
```

#### No Compression

```bash
# For already compressed files (videos, images, etc.)
srx pack video.mp4 video.srx -p "secret" -a none
```

#### Custom Chunk Size

```bash
# Larger chunks for better compression ratio
srx pack data.bin data.srx -p "key" -c 1048576  # 1 MiB chunks

# Smaller chunks for more parallelism
srx pack data.bin data.srx -p "key" -c 65536  # 64 KiB chunks
```

#### Verbose Output

```bash
# See detailed progress
srx pack file.txt file.srx -p "key" -v
```

---

## `srx unpack`

Extract an archive to retrieve the original file.

### Usage

```bash
srx unpack <INPUT> -p <PASSWORD> [OPTIONS]
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `<INPUT>` | Yes | Path to the SRX archive |

### Options

| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--password` | `-p` | (required) | Decryption password |
| `--output` | `-o` | (original name) | Output directory or filename |
| `--verbose` | `-v` | off | Enable verbose output |

### Examples

#### Basic Usage

```bash
# Extract to current directory (preserves original filename)
srx unpack archive.srx -p "my_password"
```

#### Custom Output Location

```bash
# Extract to specific directory
srx unpack archive.srx -p "my_password" -o /home/user/documents/

# Extract with specific filename
srx unpack archive.srx -p "my_password" -o restored_file.pdf
```

#### Verbose Output

```bash
# See extraction progress
srx unpack archive.srx -p "my_password" -v
```

---

## `srx info`

Display information about an archive without extracting it.

### Usage

```bash
srx info <INPUT> -p <PASSWORD>
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `<INPUT>` | Yes | Path to the SRX archive |

### Options

| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--password` | `-p` | (required) | Decryption password |
| `--json` | `-j` | off | Output in JSON format |

### Output Fields

| Field | Description |
|-------|-------------|
| `Filename` | Original filename stored in archive |
| `Original size` | Size before compression |
| `Compressed size` | Size after compression |
| `Ratio` | Compression ratio percentage |
| `Chunks` | Number of chunks in archive |
| `Compression` | Compression algorithm used |
| `Encrypted` | Whether archive is encrypted |

### Examples

#### Basic Usage

```bash
srx info archive.srx -p "my_password"
```

Output:
```
Filename: document.pdf
Original size: 1048576 bytes
Compressed size: 524288 bytes
Ratio: 50.0%
Chunks: 4
Compression: Zstd
Encrypted: true
```

#### JSON Output

```bash
srx info archive.srx -p "my_password" --json
```

Output:
```json
{
  "filename": "document.pdf",
  "original_size": 1048576,
  "compressed_size": 524288,
  "ratio": 50.0,
  "chunks": 4,
  "compression": "Zstd",
  "encrypted": true
}
```

---

## Exit Codes

SRX uses standard exit codes:

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | General error |
| `2` | Invalid arguments |
| `3` | File not found |
| `4` | Permission denied |
| `5` | Invalid password |
| `6` | Corrupted archive |
| `7` | Write error |

### Using Exit Codes in Scripts

```bash
#!/bin/bash

srx unpack archive.srx -p "password"

case $? in
    0) echo "Success!" ;;
    5) echo "Wrong password!" ;;
    6) echo "Archive is corrupted!" ;;
    *) echo "Error occurred" ;;
esac
```

---

## Environment Variables

SRX respects these environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `SRX_CHUNK_SIZE` | Default chunk size in bytes | `262144` |
| `SRX_COMPRESSION` | Default compression algorithm | `zstd` |
| `SRX_LEVEL` | Default compression level | `3` |
| `SRX_MEMORY_LIMIT` | Memory limit for Argon2 (MiB) | `64` |
| `NO_COLOR` | Disable colored output | (unset) |

### Example

```bash
# Set default compression to LZ4
export SRX_COMPRESSION=lz4

# Set default compression level
export SRX_LEVEL=5

# Now pack uses these defaults
srx pack file.txt file.srx -p "key"
```

---

## Password Input Methods

### Command Line

```bash
srx pack file.txt file.srx -p "my_password"
```

> ⚠️ **Warning:** Passwords on command line are visible in process list and shell history.

### Environment Variable

```bash
export SRX_PASSWORD="my_password"
srx pack file.txt file.srx
```

### File Input

```bash
# Read password from file
srx pack file.txt file.srx -p "$(cat ~/.password_file)"

# Or use a password manager
srx pack file.txt file.srx -p "$(pass show archives/file)"
```

### Interactive Input

```bash
# Omit password to be prompted
srx pack file.txt file.srx
# Enter password: ****
```

---

## Shell Completion

SRX supports shell completion for bash, zsh, fish, and PowerShell.

### Bash

```bash
# Add to ~/.bashrc
source <(srx completions bash)
```

### Zsh

```bash
# Add to ~/.zshrc
source <(srx completions zsh)
```

### Fish

```bash
# Add to ~/.config/fish/config.fish
srx completions fish | source
```

### PowerShell

```powershell
# Add to $PROFILE
srx completions powershell | Out-String | Invoke-Expression
```

---

## See Also

- [Getting Started](Getting-Started) - Installation and quick start
- [Library API](Library-API) - Using SRX as a Rust library
- [FAQ](FAQ) - Frequently asked questions