Back to Index

configuration commands

Configuration Commands

**Referenced Files in This Document** - [main.rs](file://src/main.rs) - [Cargo.toml](file://Cargo.toml) - [readme.md](file://readme.md)

Table of Contents

  1. Introduction
  2. Configuration File Structure
  3. CLI Command Implementation
  4. Provider Management Commands
  5. Configuration Validation and Security
  6. Common Issues and Troubleshooting
  7. Backup, Migration, and Environment Setup

Introduction

The aicommit CLI tool provides comprehensive configuration management through various commands that interact with the JSON configuration file located at ~/.aicommit.json. These commands enable users to set up AI providers, manage credentials, and modify global settings for generating git commit messages using Large Language Models (LLMs). The implementation leverages serde for serialization/deserialization and clap for argument parsing, ensuring robust and type-safe configuration handling.

The configuration system supports multiple LLM providers including OpenRouter, Ollama, and OpenAI-compatible endpoints, allowing flexibility in how users integrate AI-powered commit message generation into their development workflow. Through commands like --add-provider, --list-providers, --configure, and --reset-config, users can easily manage their provider configurations and switch between different AI services based on their needs.

This documentation details how these configuration-related CLI commands work, how they interact with the JSON configuration file, and provides guidance on best practices for setup, security, and troubleshooting common issues.

Section sources

Configuration File Structure

The configuration file ~/.aicommit.json stores all provider configurations and global settings in a structured JSON format. The file contains three main components: providers array, active_provider identifier, and retry_attempts setting.

{
  "providers": [...],
  "active_provider": "provider-id",
  "retry_attempts": 3
}

The providers array contains objects for each configured provider, with each provider having a unique ID, provider type, and specific configuration parameters. Different provider types have distinct configuration structures:

The active_provider field stores the UUID of the currently selected provider, determining which service is used for generating commit messages. The retry_attempts parameter specifies how many times the system should attempt to generate a commit message if the initial request fails, with a default value of 3 attempts and 5-second intervals between retries.

For Simple Free OpenRouter configuration, additional fields track model performance over time:

These fields enable the sophisticated failover mechanism that automatically switches between free models based on reliability and availability.

Section sources

CLI Command Implementation

The CLI command implementation in src/main.rs uses clap for argument parsing and serde for configuration serialization. The Cli struct defined with #[derive(Parser)] contains all command-line options, with specific attributes mapping to the desired CLI flags.

classDiagram
class Cli {
+add_provider : bool
+add : bool
+add_openrouter : bool
+openrouter_api_key : Option<String>
+openrouter_model : String
+add_simple_free : bool
+add_ollama : bool
+ollama_url : String
+ollama_model : String
+add_openai_compatible : bool
+openai_compatible_api_key : Option<String>
+openai_compatible_api_url : Option<String>
+openai_compatible_model : String
+max_tokens : i32
+temperature : f32
+list : bool
+set : Option<String>
+config : bool
+version_file : Option<String>
+version_iterate : bool
+version_cargo : bool
+version_npm : bool
+version_github : bool
+dry_run : bool
+pull : bool
+watch : bool
+wait_for_edit : Option<String>
+push : bool
+help : bool
+version : bool
+verbose : bool
+no_gitignore_check : bool
+msg : Option<String>
+simulate_offline : bool
+jail_status : bool
+unjail : Option<String>
+unjail_all : bool
}
class Config {
+providers : Vec<ProviderConfig>
+active_provider : String
+retry_attempts : u32
}
class ProviderConfig {
<<enum>>
+OpenRouter(OpenRouterConfig)
+Ollama(OllamaConfig)
+OpenAICompatible(OpenAICompatibleConfig)
+SimpleFreeOpenRouter(SimpleFreeOpenRouterConfig)
}
class OpenRouterConfig {
+id : String
+provider : String
+api_key : String
+model : String
+max_tokens : i32
+temperature : f32
}
class OllamaConfig {
+id : String
+provider : String
+model : String
+url : String
+max_tokens : i32
+temperature : f32
}
class OpenAICompatibleConfig {
+id : String
+provider : String
+api_key : String
+api_url : String
+model : String
+max_tokens : i32
+temperature : f32
}
class SimpleFreeOpenRouterConfig {
+id : String
+provider : String
+api_key : String
+max_tokens : i32
+temperature : f32
+failed_models : Vec<String>
+model_stats : HashMap<String, ModelStats>
+last_used_model : Option<String>
+last_config_update : DateTime<Utc>
}
class ModelStats {
+success_count : usize
+failure_count : usize
+last_success : Option<DateTime<Utc>>
+last_failure : Option<DateTime<Utc>>
+jail_until : Option<DateTime<Utc>>
+jail_count : usize
+blacklisted : bool
+blacklisted_since : Option<DateTime<Utc>>
}
Config --> ProviderConfig : "contains"
ProviderConfig --> OpenRouterConfig : "variant"
ProviderConfig --> OllamaConfig : "variant"
ProviderConfig --> OpenAICompatibleConfig : "variant"
ProviderConfig --> SimpleFreeOpenRouterConfig : "variant"
SimpleFreeOpenRouterConfig --> ModelStats : "contains"

**Diagram sources **

The main function processes these commands through pattern matching on the CLI arguments. When a configuration command is detected, it either loads the existing configuration or creates a new one, modifies it according to the command, and saves it back to the JSON file. The Config::load() method handles reading and parsing the configuration file, while various setup methods handle the creation and modification of provider configurations.

For non-interactive provider addition (e.g., --add-openrouter), the configuration is created directly from the provided command-line arguments. For interactive mode (--add-provider), the dialoguer crate provides a user-friendly interface to collect the necessary information through prompts and selection menus.

The configuration file is saved using serde_json’s pretty printing functionality, ensuring human-readable JSON output with proper indentation and formatting. Error handling is implemented throughout to provide meaningful feedback if configuration operations fail due to permission issues, invalid data, or I/O errors.

Section sources

Provider Management Commands

The provider management commands enable users to add, list, and configure different AI providers for commit message generation. Each command interacts with the JSON configuration file to persist changes across sessions.

Add Provider Command

The --add-provider command initiates an interactive setup process that guides users through configuring a new provider. When executed, it presents a menu of available provider types:

aicommit --add-provider

Users can select from:

For the recommended “Free OpenRouter” option, users only need to provide an OpenRouter API key. The system automatically queries OpenRouter’s API for available free models and implements an intelligent selection algorithm based on a predefined ranking of preferred models.

Non-interactive provider addition allows for scriptable configuration:

# Add OpenRouter provider
aicommit --add-provider --add-openrouter --openrouter-api-key "your-api-key" --openrouter-model "mistralai/mistral-tiny"

# Add Simple Free OpenRouter provider
aicommit --add-provider --add-simple-free --openrouter-api-key "your-api-key"

# Add Ollama provider
aicommit --add-provider --add-ollama --ollama-url "http://localhost:11434" --ollama-model "llama2"

# Add OpenAI compatible provider
aicommit --add-provider --add-openai-compatible \
  --openai-compatible-api-key "your-api-key" \
  --openai-compatible-api-url "https://api.deep-foundation.tech/v1/chat/completions" \
  --openai-compatible-model "gpt-4o-mini"

All non-interactive commands support optional parameters for --max-tokens (default: 200) and --temperature (default: 0.2) to customize the AI response characteristics.

List Providers Command

The --list command displays all configured providers with their IDs:

aicommit --list

Output shows each provider type and its unique identifier:

OpenRouter: 550e8400-e29b-41d4-a716-446655440000
Ollama: 67e55044-10b1-426f-9247-bb680e5fe0c8
Simple Free OpenRouter: 789e1234-abcd-5678-efgh-ijklmnopqrstuv

This information is essential for switching between providers using the --set command.

Set Active Provider Command

The --set command activates a specific provider by its ID:

aicommit --set <provider-id>

The command validates that the specified provider ID exists in the configuration before updating the active_provider field. If the provider is not found, it returns an error message indicating the missing provider.

Configure Command

The --config command opens the configuration file in the user’s default editor:

aicommit --config

If no editor is specified in the EDITOR environment variable, it defaults to vim. The command ensures the configuration file exists by creating a default configuration if needed, then launches the editor for direct modification of the JSON structure.

sequenceDiagram
participant User
participant CLI as aicommit CLI
participant Config as Config Module
participant FS as File System
User->>CLI : Execute --add-provider
CLI->>Config : Parse CLI arguments
Config->>User : Display provider selection menu
User->>Config : Select provider type
Config->>User : Prompt for required parameters
User->>Config : Provide configuration values
Config->>Config : Create new provider configuration
Config->>FS : Load existing config or create default
Config->>Config : Add new provider to providers array
Config->>Config : Set as active provider
Config->>FS : Save updated config to ~/.aicommit.json
Config->>CLI : Return success status
CLI->>User : Display "Provider added successfully!"

**Diagram sources **

Section sources

Configuration Validation and Security

The configuration system implements several validation and security measures to ensure reliable operation and protect sensitive information.

Configuration Validation

When loading the configuration file, the system performs multiple validation checks:

The Config::load() method returns descriptive error messages for different failure scenarios:

For provider-specific validation, the system ensures required parameters are present:

Security Considerations

The configuration system handles sensitive data with appropriate security measures:

API keys are stored in plain text within the JSON configuration file, but the file is created with restrictive permissions (typically 600) to prevent unauthorized access. The configuration file is stored in the user’s home directory (~/.aicommit.json), which is generally protected from other users on multi-user systems.

For enhanced security, users can leverage environment variables instead of storing API keys directly in the configuration. While not explicitly implemented in the current code, this could be achieved by modifying the CLI argument parsing to check environment variables when API key parameters are empty.

The system also creates a default .gitignore file in the user’s home directory to prevent accidental commits of sensitive configuration files. This helps avoid the common mistake of committing API keys to version control repositories.

When making API requests, the system includes appropriate headers to identify the application:

These headers help API providers understand the source of requests while maintaining security through proper authentication.

Section sources

Common Issues and Troubleshooting

Several common issues may arise when working with the configuration system, along with their solutions.

Malformed Configuration Files

Malformed JSON in the configuration file can prevent the tool from starting. Symptoms include:

Solutions:

  1. Use aicommit --config to open the file in an editor with JSON syntax highlighting
  2. Validate JSON structure using online tools or command-line utilities like jq
  3. Check for common issues: missing commas, unbalanced brackets, improper quotes
  4. As a last resort, rename the corrupted file and start fresh with aicommit --add-provider

Duplicate Providers

While the system allows multiple providers of the same type, having too many can make management difficult. To avoid confusion:

Permission Errors

Permission errors typically occur when:

Solutions:

  1. Verify the user has read/write permissions to the home directory
  2. Check file ownership and permissions of ~/.aicommit.json
  3. Run the tool with appropriate privileges if needed
  4. Consider alternative configuration locations if home directory access is restricted

Network Connectivity Issues

For cloud-based providers like OpenRouter, network issues can affect configuration:

The system includes resilience features:

Users experiencing persistent connectivity issues should:

  1. Verify internet connection
  2. Check if the API provider is operational
  3. Consider using local providers like Ollama as alternatives
  4. Use the --simulate-offline flag for testing in disconnected environments

The --jail-status, --unjail, and --unjail-all commands provide additional troubleshooting capabilities for the Simple Free OpenRouter mode, allowing users to inspect and modify the model management system that tracks model reliability over time.

Section sources

Backup, Migration, and Environment Setup

Effective backup, migration, and environment-specific setup strategies ensure consistent configuration across different systems and protect against data loss.

Backup Strategies

Regular backups of the configuration file are essential:

# Manual backup
cp ~/.aicommit.json ~/.aicommit.json.backup.$(date +%Y%m%d)

# Automated backup script
#!/bin/bash
CONFIG_FILE="$HOME/.aicommit.json"
BACKUP_DIR="$HOME/.aicommit_backups"
mkdir -p "$BACKUP_DIR"
cp "$CONFIG_FILE" "$BACKUP_DIR/config_$(date +%Y%m%d_%H%M%S).json"

Recommended backup practices:

Migration Between Systems

To migrate configurations between computers:

  1. Copy the ~/.aicommit.json file to the new system
  2. Ensure the target system has the aicommit tool installed
  3. Verify file permissions are correctly set (600)
  4. Test the configuration with a simple command

For team environments, consider:

Environment-Specific Setup

Environment variables can override or supplement configuration settings:

# Set environment variables
export AICOMMIT_OPENROUTER_API_KEY="your-key-here"
export AICOMMIT_OLLAMA_URL="http://localhost:11434"
export EDITOR="nano"

# Use in scripts
AICOMMIT_OPENROUTER_API_KEY="temp-key" aicommit --add-simple-free --openrouter-api-key=$AICOMMIT_OPENROUTER_API_KEY

Different environments might require different configurations:

The system supports environment-specific behavior through:

For complex deployment scenarios, consider using configuration management tools like Ansible, Puppet, or Chef to ensure consistent setup across multiple systems.

Section sources