Enum ConfigAction

pub enum ConfigAction {
    Set {
        key: String,
        value: String,
    },
    Get {
        key: String,
    },
    List,
    Reset,
}

Configuration management operations and subcommands.

Defines the available configuration management operations that can be performed through the SubX CLI. Each operation provides specific functionality for different aspects of configuration management.

Operation Categories

• Viewing: Get and list operations for inspecting settings
• Modification: Set operation for changing configuration values
• Maintenance: Reset operation for restoring defaults

Validation and Safety

All configuration operations include:

• Type validation: Ensure values match expected data types
• Range checking: Validate numeric values are within acceptable ranges
• Format verification: Check string values follow required patterns
• Dependency checking: Verify related settings are compatible

Examples

use subx_cli::cli::ConfigAction;

// Different configuration operations
let set_provider = ConfigAction::Set {
    key: "ai.provider".to_string(),
    value: "openai".to_string(),
};

let get_provider = ConfigAction::Get {
    key: "ai.provider".to_string(),
};

let list_all = ConfigAction::List;
let reset_config = ConfigAction::Reset;

Variants

Set

Set a configuration value with validation and type checking.

Updates a specific configuration setting with the provided value. The operation includes comprehensive validation to ensure the new value is compatible with the setting’s type and constraints.

Key Format

Configuration keys use dot notation to navigate the hierarchy:

• ai.provider - AI service provider selection
• ai.openai.api_key - OpenAI API key
• general.enable_progress_bar - Progress bar display preference
• audio.max_offset_seconds - Maximum sync offset range

Value Types and Examples

# String values
subx config set ai.provider "openai"
subx config set ai.openai.api_key "sk-..."

# Boolean values
subx config set general.enable_progress_bar true
subx config set ai.enable_cache false

# Numeric values
subx config set audio.max_offset_seconds 30.0
subx config set ai.max_sample_length 2000

# Array values (JSON format)
subx config set ai.supported_models '["gpt-4.1"]'

Validation Rules

• API Keys: Must match provider-specific format requirements
• URLs: Must be valid HTTP/HTTPS endpoints
• File Paths: Must be accessible and have appropriate permissions
• Numeric Ranges: Must fall within acceptable min/max values
• Enum Values: Must match predefined valid options

Error Handling

Common validation errors and solutions:

• Invalid key: Check key spelling and available options
• Type mismatch: Verify value format matches expected type
• Range error: Ensure numeric values are within valid range
• Permission error: Check file/directory access permissions

Fields

key: String

Configuration key in dot notation (e.g., “ai.provider”, “general.timeout”).

Specifies the configuration setting to modify using hierarchical dot notation. The key must correspond to a valid configuration setting as defined in the application’s configuration schema.

Key Categories

• ai.*: AI service configuration and credentials
• audio.*: Audio processing and synchronization settings
• general.*: Basic application behavior and preferences
• cache.*: Caching behavior and storage settings
• format.*: Default output formats and encoding options

Examples

subx config set ai.provider openai
subx config set general.enable_progress_bar false
subx config set audio.correlation_threshold 0.8

value: String

New value for the configuration setting.

The value to assign to the specified configuration key. The value will be validated against the setting’s type and constraints before being applied. String values containing spaces should be quoted.

Type Conversion

Values are automatically converted to the appropriate type:

• Strings: Used as-is or with quotes for spaces
• Booleans: “true”, “false”, “1”, “0”, “yes”, “no”
• Numbers: Integer or floating-point notation
• Arrays: JSON array format for complex values

Special Values

• Empty string: "" to clear string settings
• Null/None: null to unset optional settings
• Environment variables: ${VAR_NAME} for dynamic values

Examples

subx config set ai.openai.api_key "sk-1234567890abcdef"
subx config set general.timeout 30
subx config set audio.enabled true
subx config set cache.max_size_mb 512

Get

Retrieve and display a specific configuration value.

Displays the current value of a configuration setting along with metadata such as the source of the setting (user config, system default, environment variable, etc.) and any applicable constraints.

Output Format

The command displays:

• Current Value: The effective value being used
• Source: Where the value originates (user, system, environment)
• Default Value: The built-in default if different from current
• Type Information: Expected value type and constraints
• Description: Human-readable explanation of the setting

Examples

subx config get ai.provider
# Output:
# ai.provider = "openai"
# Source: user config (/home/user/.config/subx/config.toml)
# Default: "openai"
# Type: String (enum: openai, anthropic, local)
# Description: AI service provider for subtitle matching

subx config get general.enable_progress_bar
# Output:
# general.enable_progress_bar = true
# Source: system default
# Type: Boolean
# Description: Show progress bars during long operations

Use Cases

• Debugging: Verify current configuration values
• Documentation: Understand setting sources and constraints
• Validation: Confirm settings are applied correctly
• Troubleshooting: Identify configuration-related issues

Fields

key: String

Configuration key to retrieve (e.g., “ai.provider”, “general.timeout”).

Specifies which configuration setting to display. The key must correspond to a valid configuration setting. Use subx config list to see all available configuration keys.

Wildcard Support

Future enhancement will support wildcard patterns:

• ai.* - All AI-related settings
• *.timeout - All timeout settings
• general.* - All general application settings

Examples

subx config get ai.provider
subx config get general.enable_progress_bar
subx config get audio.correlation_threshold

List

List all configuration settings with their current values.

Displays a comprehensive overview of all configuration settings organized by category. This provides a complete view of the current configuration state and helps identify settings that may need adjustment.

Output Organization

Settings are grouped by category:

• General: Basic application behavior
• AI: AI service configuration and parameters
• Audio: Audio processing and synchronization
• Cache: Caching behavior and storage
• Format: Output format and encoding preferences

Information Displayed

For each setting:

• Key: Full configuration key path
• Value: Current effective value
• Source: Configuration source (user/system/env/default)
• Type: Data type and constraints
• Status: Modified/default indicator

Filtering Options

Future enhancements will include:

• Category filtering (--category ai)
• Modified-only view (--modified-only)
• Source filtering (--source user)
• Output format options (--format json)

Examples

subx config list
# Output:
# [General]
# enable_progress_bar = true (default)
# timeout = 30 (user)
#
# [AI]
# provider = "openai" (user)
# openai.api_key = "sk-***" (env: OPENAI_API_KEY)
# max_sample_length = 2000 (default)
#
# [Audio]
# max_offset_seconds = 30.0 (default)
# correlation_threshold = 0.8 (user)

Use Cases

• Configuration Review: Audit current settings
• Troubleshooting: Identify problematic configurations
• Documentation: Generate configuration documentation
• Migration: Prepare for configuration transfer

Reset

Reset configuration to default values with backup creation.

Restores all configuration settings to their built-in default values. This operation creates a backup of the current configuration before making changes, allowing for easy recovery if needed.

Reset Scope

The reset operation affects:

• User Configuration: Settings in user config directory
• Project Configuration: Local project-specific settings
• Cached Values: Processed configuration cache

Data Preserved

The following are NOT affected by reset:

• Environment Variables: Runtime configuration overrides
• Command-line Arguments: Temporary session overrides
• System Configuration: Global system-wide settings
• Application Data: Caches, logs, and processing results

Backup Process

Before resetting:

1. Backup Creation: Current config saved with timestamp
2. Verification: Ensure backup was created successfully
3. Reset Application: Apply default values
4. Validation: Verify new configuration is valid

Backup Location

Backups are stored in the configuration directory:

~/.config/subx/backups/config_backup_YYYYMMDD_HHMMSS.toml

Recovery

To restore from backup:

# Copy backup back to main config
cp ~/.config/subx/backups/config_backup_20240101_120000.toml \
   ~/.config/subx/config.toml

Confirmation

This is a destructive operation that requires user confirmation:

subx config reset
# Output:
# ⚠ This will reset all configuration to defaults
# ⚠ Current config will be backed up to: ~/.config/subx/backups/...
# Continue? [y/N]:

Use Cases

• Fresh Start: Clean slate for new configuration
• Troubleshooting: Eliminate configuration-related issues
• Testing: Ensure tests run with predictable defaults
• Migration: Prepare for major version upgrades

Examples

subx config reset
# Interactive confirmation and backup creation

subx config reset --force
# Skip confirmation (future enhancement)

subx config reset --dry-run
# Show what would be reset without making changes

Trait Implementations

impl Debug for ConfigAction

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromArgMatches for ConfigAction

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut<'b>( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Subcommand for ConfigAction

fn augment_subcommands<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_subcommands_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

fn has_subcommand(__clap_name: &str) -> bool

Test whether Self can parse a specific subcommand