# Command Line Interface (CLI)

The Watch Finished Turbo CLI provides comprehensive command-line access to all system functionality, including task management, queue configuration, file operations, and system monitoring.

## Installation

The CLI is built into the main application. When running in development mode, use:

```bash
pnpm run cli
```

For production deployments, the CLI is available as part of the service container.

## Command Structure

All commands follow the pattern: `watch-finished-cli <command> [options]`

## Task Management Commands

### Task Listing and Inspection

#### `task:list`

List all tasks in the system.

```bash
watch-finished-cli task:list
```

Displays a table of all tasks with their current status, progress, priority, and retry information.

#### `task:get`

Get detailed information about a specific task.

```bash
watch-finished-cli task:get --id 123
```

**Options:**

- `--id <id>`: Task ID (required)

Returns complete task details including input/output paths, preset, retry count, and timestamps.

#### `task:delete`

Delete a task from the system.

```bash
watch-finished-cli task:delete --id 123
```

**Options:**

- `--id <id>`: Task ID (required)

Permanently removes the task from the database.

### Queue Management

#### `task:queue:status`

Get current queue status and statistics.

```bash
watch-finished-cli task:queue:status
```

Returns information about:

- Active tasks currently processing
- Pending tasks in queue
- Failed tasks awaiting retry
- Processing statistics

#### `task:queue:settings`

Display current queue configuration settings.

```bash
watch-finished-cli task:queue:settings
```

Shows all queue settings including batch size, concurrency, retry configuration, and processing intervals.

#### `task:queue:settings:update`

Update queue configuration settings.

```bash
# Set batch size to 5 and concurrency to 2
watch-finished-cli task:queue:settings:update --batch-size 5 --concurrency 2

# Configure retry settings
watch-finished-cli task:queue:settings:update --max-retries 5 --retry-delay 60000

# Disable retries
watch-finished-cli task:queue:settings:update --retry-enabled false
```

**Options:**

- `--batch-size <size>`: Number of tasks to process in each batch
- `--concurrency <count>`: Maximum number of concurrent tasks
- `--retry-enabled <true|false>`: Enable/disable automatic retries
- `--max-retries <count>`: Maximum retry attempts for failed tasks
- `--retry-delay <ms>`: Delay between retry attempts in milliseconds
- `--processing-interval <ms>`: How often to check for new tasks in milliseconds

## File Management Commands

### File Operations

#### `list`

List files in a dataset with optional status filtering.

```bash
# List all successful files in movies dataset
watch-finished-cli list --dataset movies --status success

# List all files (default status is success)
watch-finished-cli list --dataset movies
```

**Options:**

- `--dataset <dataset>`: Dataset name (required)
- `--status <status>`: File status filter (default: "success")

#### `file:get`

Get detailed information about a specific file record.

```bash
watch-finished-cli file:get --dataset movies --file "movie.mkv"
```

**Options:**

- `--dataset <dataset>`: Dataset name (required)
- `--file <file>`: Input file path (required)

#### `file:set`

Create or update a file record.

```bash
# Create/update a file record with output path
watch-finished-cli file:set --dataset movies --file "input.mkv" --output "output.mp4"

# Update file status
watch-finished-cli file:set --dataset movies --file "movie.mkv" --status "processing"
```

**Options:**

- `--dataset <dataset>`: Dataset name (required)
- `--file <file>`: Input file path (required)
- `--output <output>`: Output file path
- `--status <status>`: File status
- `--date <date>`: ISO date string

#### `file:remove`

Remove a file record (soft delete by default).

```bash
# Soft delete (marks as deleted)
watch-finished-cli file:remove --dataset movies --file "old-movie.mkv"

# Hard delete (permanently remove)
watch-finished-cli file:remove --dataset movies --file "old-movie.mkv" --soft false
```

**Options:**

- `--dataset <dataset>`: Dataset name (required)
- `--file <file>`: Input file path (required)
- `--soft <true|false>`: Soft delete flag (default: true)

#### `files:deleted-older-than`

Get deleted files older than a specified date.

```bash
watch-finished-cli files:deleted-older-than --dataset movies --isoDate "2024-01-01T00:00:00.000Z"
```

**Options:**

- `--dataset <dataset>`: Dataset name (required)
- `--isoDate <isoDate>`: ISO date string (required)

## Configuration Management

### Settings Operations

#### `config:list`

List all available configuration files.

```bash
watch-finished-cli config:list
```

#### `config:settings`

Get configuration settings, optionally filtered by key.

```bash
# Get all settings
watch-finished-cli config:settings

# Get specific setting
watch-finished-cli config:settings --key queue
```

**Options:**

- `--key <key>`: Settings key to retrieve

#### `config:file`

Get the contents of a specific configuration file.

```bash
watch-finished-cli config:file --name datasets
```

**Options:**

- `--name <name>`: Configuration file name (required)

## Watcher Management

### File System Monitoring

#### `watcher:start`

Start the file system watcher with specified directories.

```bash
watch-finished-cli watcher:start --watches "/data/movies,/data/tvshows"
```

**Options:**

- `--watches <watches>`: Comma-separated list of directories to watch (required)

#### `watcher:stop`

Stop the file system watcher.

```bash
watch-finished-cli watcher:stop
```

#### `watcher:status`

Get current watcher status.

```bash
watch-finished-cli watcher:status
```

## HandBrake Operations

#### `handbrake:presets`

List all available HandBrake presets.

```bash
watch-finished-cli handbrake:presets
```

#### `handbrake:process`

Process a video file directly with HandBrake (bypasses queue system).

```bash
watch-finished-cli handbrake:process --input "input.mkv" --output "output.mp4" --preset "Fast 1080p30"
```

**Options:**

- `--input <input>`: Input file path (required)
- `--output <output>`: Output file path (required)
- `--preset <preset>`: HandBrake preset name (required)

## Maintenance Operations

### System Maintenance

#### `maintenance:cleanup`

Clean up a file record if the file no longer exists.

```bash
watch-finished-cli maintenance:cleanup --file "/data/movies/old-file.mkv" --dirs "/data/movies"
```

**Options:**

- `--file <file>`: File path to check (required)
- `--dirs <dirs>`: Comma-separated list of directories to search (required)

#### `maintenance:purge`

Purge deleted records older than specified thresholds.

```bash
# Purge records older than default thresholds
watch-finished-cli maintenance:purge --dirs "/data/movies,/data/tvshows"

# Custom age and cleanup intervals
watch-finished-cli maintenance:purge --dirs "/data/movies" --dayMs 86400000 --cleanerMs 3600000
```

**Options:**

- `--dirs <dirs>`: Comma-separated list of directories (required)
- `--dayMs <dayMs>`: Age threshold in milliseconds
- `--cleanerMs <cleanerMs>`: Cleanup interval in milliseconds

#### `maintenance:prune`

Prune processed files that no longer exist on disk.

```bash
watch-finished-cli maintenance:prune --dirs "/data/movies,/data/tvshows"
```

**Options:**

- `--dirs <dirs>`: Comma-separated list of directories (required)

## Queue Settings Reference

The task queue supports the following configuration options:

| Setting              | Description                | Default | Example                       |
| -------------------- | -------------------------- | ------- | ----------------------------- |
| `batchSize`          | Tasks processed per batch  | 10      | `--batch-size 5`              |
| `concurrency`        | Maximum concurrent tasks   | 1       | `--concurrency 3`             |
| `retryEnabled`       | Enable automatic retries   | true    | `--retry-enabled false`       |
| `maxRetries`         | Maximum retry attempts     | 3       | `--max-retries 5`             |
| `retryDelay`         | Delay between retries (ms) | 30000   | `--retry-delay 60000`         |
| `processingInterval` | Queue check interval (ms)  | 5000    | `--processing-interval 10000` |

## Examples

### Complete Workflow

```bash
# Start watching directories
watch-finished-cli watcher:start --watches "/data/movies,/data/tvshows"

# Configure queue for high-throughput processing
watch-finished-cli task:queue:settings:update --batch-size 10 --concurrency 3 --max-retries 5

# Monitor queue status
watch-finished-cli task:queue:status

# List current tasks
watch-finished-cli task:list

# Check specific task details
watch-finished-cli task:get --id 123

# View queue configuration
watch-finished-cli task:queue:settings

# Adjust settings for lower resource usage
watch-finished-cli task:queue:settings:update --concurrency 1 --processing-interval 10000
```

### Troubleshooting Failed Tasks

```bash
# Find failed tasks
watch-finished-cli task:list | grep failed

# Get details of failed task
watch-finished-cli task:get --id 456

# Manually requeue with higher priority
# (Note: requeue is done through the web UI or by creating new tasks)

# Adjust retry settings if needed
watch-finished-cli task:queue:settings:update --max-retries 10 --retry-delay 120000
```

### Configuration Management

```bash
# View current settings
watch-finished-cli config:settings

# View queue-specific settings
watch-finished-cli config:settings --key queue

# List available config files
watch-finished-cli config:list

# View dataset configuration
watch-finished-cli config:file --name datasets
```

## Error Handling

The CLI provides clear error messages for common issues:

- **Connection errors**: Check that the service is running and accessible
- **Invalid options**: Use `--help` with any command to see valid options
- **Permission errors**: Ensure proper file system permissions for watched directories
- **Configuration errors**: Verify configuration files are valid JSON

## Integration with Scripts

The CLI can be easily integrated into shell scripts and automation workflows:

```bash
#!/bin/bash
# Daily maintenance script

echo "Starting daily maintenance..."

# Purge old records
watch-finished-cli maintenance:purge --dirs "/data/movies,/data/tvshows"

# Prune missing files
watch-finished-cli maintenance:prune --dirs "/data/movies,/data/tvshows"

# Check queue health
STATUS=$(watch-finished-cli task:queue:status)
echo "Queue status: $STATUS"

echo "Maintenance complete."
```