watch-finished-turbo/docs/cli.md

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:

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.

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.

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.

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.

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.

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.

# 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 pulled from queue for consideration in each processing cycle (default: 10). Controls how many pending tasks are evaluated at once.
• --concurrency <count>: Maximum number of tasks that can process simultaneously (default: 1). Limits parallel execution to prevent system overload.
• --retry-enabled <true|false>: Enable/disable automatic retries for failed tasks (default: true)
• --max-retries <count>: Maximum retry attempts for failed tasks (default: 3). Total attempts = maxRetries + 1.
• --retry-delay <ms>: Delay between retry attempts in milliseconds (default: 30000)
• --processing-interval <ms>: How often to check for new tasks in milliseconds (default: 5000)

File Management Commands

File Operations

list

List files in a dataset with optional status filtering.

# 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.

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.

# 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).

# 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.

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.

watch-finished-cli config:list

config:settings

Get configuration settings, optionally filtered by key.

# 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.

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.

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.

watch-finished-cli watcher:stop

watcher:status

Get current watcher status.

watch-finished-cli watcher:status

HandBrake Operations

handbrake:presets

List all available HandBrake presets.

watch-finished-cli handbrake:presets

handbrake:process

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

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.

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.

# 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.

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

# 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

# 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

# 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:

#!/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."