# CLI Options for Global Installation

This document explains how to use the AI Developer Assistant (`ai-dev`) when installed globally via npm without local configuration files.

## Overview

When you install the package globally with `npm install -g kg6-codex`, it can't access your local `.env` files or configuration files. Instead, you can pass all configuration options directly via command-line arguments.

## Installation

```bash
npm install -g kg6-codex
```

## Basic Usage

```bash
ai-dev <command> [options]
```

## Available CLI Options

### LLM Provider Configuration

```bash
--llm-provider <provider>     # LLM provider: openai, ollama, gemini
--llm-model <model>           # Model name (e.g., gpt-4, llama2, gemini-pro)
--llm-temperature <temp>      # Temperature (0-1, default: 0.7)
--llm-max-tokens <tokens>     # Maximum tokens (default: 1000)
```

### OpenAI Configuration

```bash
--openai-api-key <key>        # Your OpenAI API key (required for OpenAI)
--openai-base-url <url>       # Custom OpenAI API base URL
--openai-organization <org>   # OpenAI organization ID
```

### Google Gemini Configuration

```bash
--gemini-api-key <key>        # Your Google Gemini API key (required for Gemini)
--gemini-model <model>        # Gemini model name (default: gemini-pro)
```

### Ollama Configuration

```bash
--ollama-enabled              # Enable Ollama (local LLM)
--ollama-base-url <url>       # Ollama base URL (default: http://localhost:11434)
--ollama-model <model>        # Ollama model name
```

### GitHub Integration

```bash
--github-token <token>        # GitHub personal access token
--github-base-url <url>       # GitHub API base URL (for GitHub Enterprise)
```

### Git Configuration

```bash
--git-repo-path <path>        # Git repository path
--git-default-branch <branch> # Default branch name
--git-include-staged          # Include staged changes
--git-include-unstaged        # Include unstaged changes
```

### Output Configuration

```bash
--output-format <format>      # Output format: console, markdown, json, html, file
--output-path <path>          # Output file path (for file format)
--output-verbose              # Enable verbose output
--output-colorize             # Enable colored output
```

### Security Scanning

```bash
--security-enabled            # Enable security scanning
--security-severity <levels>  # Severity levels: low,medium,high,critical
--security-categories <cats>  # Categories: injection,auth,crypto,etc.
```

### File Patterns

```bash
--file-patterns <patterns>    # Include patterns (comma-separated)
--exclude-patterns <patterns> # Exclude patterns (comma-separated)
```

## Example Commands

### Code Review with OpenAI

```bash
ai-dev review \
  --llm-provider openai \
  --openai-api-key sk-your-openai-key-here \
  --llm-model gpt-4 \
  --output-format console \
  --verbose
```

### Code Explanation with Gemini

```bash
ai-dev explain \
  --llm-provider gemini \
  --gemini-api-key your-gemini-key \
  --file-patterns "src/**/*.ts,src/**/*.js" \
  --output-format markdown \
  --output-path explanation.md
```

### Security Scan

```bash
ai-dev security-scan \
  --llm-provider openai \
  --openai-api-key sk-your-key \
  --security-enabled \
  --security-severity high,critical \
  --file-patterns "src/**/*.ts"
```

### Commit Message Generation

```bash
ai-dev commit-msg \
  --llm-provider ollama \
  --ollama-enabled \
  --ollama-model llama2 \
  --git-include-staged \
  --output-format console
```

### Documentation Generation

```bash
ai-dev docs \
  --llm-provider openai \
  --openai-api-key sk-your-key \
  --file-patterns "src/**/*.ts" \
  --output-format markdown \
  --output-path docs/api.md
```

## Environment Variables Alternative

You can set system environment variables instead of using CLI options. Environment variables are automatically detected and used as fallbacks when CLI options are not provided.

### Setting Environment Variables

**In your shell profile** (`.bashrc`, `.zshrc`, etc.):
```bash
# LLM Configuration
export LLM_PROVIDER="gemini"
export LLM_MODEL="gemini-2.0-flash"
export LLM_TEMPERATURE="0.7"
export LLM_MAX_TOKENS="2000"

# API Keys
export GEMINI_API_KEY="sk-your-api-key-here"
export OPENAI_API_KEY="sk-your-openai-key-here"
export GITHUB_TOKEN="ghp_your-github-token"

# Git Configuration
export GIT_REPO_PATH="/path/to/your/repo"
export GIT_DEFAULT_BRANCH="main"
export GIT_INCLUDE_STAGED="true"
export GIT_INCLUDE_UNSTAGED="true"

# Output Configuration
export OUTPUT_FORMAT="console"
export OUTPUT_VERBOSE="true"
export OUTPUT_COLORIZE="true"

# Security Configuration
export SECURITY_ENABLED="true"
export SECURITY_SEVERITY="high,critical"
export SECURITY_CATEGORIES="injection,authentication"

# File Patterns
export FILE_PATTERNS="src/**/*.ts,src/**/*.js"
export EXCLUDE_PATTERNS="node_modules/**,dist/**"
```

**For current session only:**
```bash
export LLM_PROVIDER="gemini"
export GEMINI_API_KEY="sk-your-api-key-here"
export LLM_MODEL="gemini-2.0-flash"

ai-dev review --verbose
```

### Your Gemini Setup Example

Based on your environment variables, here's how to set them up permanently:

**Add to your shell profile** (`.bashrc`, `.zshrc`, etc.):
```bash
# Gemini Configuration
export GEMINI_API_KEY="sk-your-api-key-here"
export LLM_PROVIDER="gemini"
export LLM_MODEL="gemini-2.0-flash"
```

**Then simply run:**
```bash
ai-dev review                    # Uses your environment variables automatically
ai-dev explain                   # No need to specify API keys or provider
ai-dev security-scan            # All settings inherited from environment
```

### Complete List of Environment Variables

| Environment Variable | Description | Example Value |
|---------------------|-------------|---------------|
| `LLM_PROVIDER` | LLM provider (openai, ollama, gemini) | `gemini` |
| `LLM_MODEL` | Model name | `gemini-2.0-flash` |
| `LLM_TEMPERATURE` | Temperature (0-1) | `0.7` |
| `LLM_MAX_TOKENS` | Maximum tokens | `2000` |
| `OPENAI_API_KEY` | OpenAI API key | `sk-...` |
| `OPENAI_BASE_URL` | OpenAI base URL | `https://api.openai.com/v1` |
| `OPENAI_ORGANIZATION` | OpenAI organization ID | `org-...` |
| `GEMINI_API_KEY` | Google Gemini API key | `AIzaSy...` |
| `GEMINI_MODEL` | Gemini model name | `gemini-pro` |
| `OLLAMA_ENABLED` | Enable Ollama (true/false) | `true` |
| `OLLAMA_BASE_URL` | Ollama base URL | `http://localhost:11434` |
| `OLLAMA_MODEL` | Ollama model name | `llama2` |
| `GITHUB_TOKEN` | GitHub personal access token | `ghp_...` |
| `GITHUB_BASE_URL` | GitHub API base URL | `https://api.github.com` |
| `GIT_REPO_PATH` | Git repository path | `/path/to/repo` |
| `GIT_DEFAULT_BRANCH` | Default branch name | `main` |
| `GIT_INCLUDE_STAGED` | Include staged changes (true/false) | `true` |
| `GIT_INCLUDE_UNSTAGED` | Include unstaged changes (true/false) | `true` |
| `OUTPUT_FORMAT` | Output format | `console` |
| `OUTPUT_PATH` | Output file path | `/path/to/output.md` |
| `OUTPUT_VERBOSE` | Enable verbose output (true/false) | `true` |
| `OUTPUT_COLORIZE` | Enable colored output (true/false) | `true` |
| `SECURITY_ENABLED` | Enable security scanning (true/false) | `true` |
| `SECURITY_SEVERITY` | Severity levels (comma-separated) | `high,critical` |
| `SECURITY_CATEGORIES` | Categories (comma-separated) | `injection,auth` |
| `FILE_PATTERNS` | Include patterns (comma-separated) | `src/**/*.ts` |
| `EXCLUDE_PATTERNS` | Exclude patterns (comma-separated) | `node_modules/**` |

## Configuration Priority

CLI options have the highest priority and override:
1. Configuration files
2. Environment variables
3. Default values

## Getting Help

```bash
ai-dev --help                    # Show global options
ai-dev <command> --help          # Show command-specific options
ai-dev config show              # Show current configuration
```

## Common Use Cases

### Quick Setup Script

Create a shell script to avoid typing long commands:

```bash
#!/bin/bash
# review.sh
ai-dev review \
  --llm-provider openai \
  --openai-api-key "$OPENAI_API_KEY" \
  --llm-model gpt-4 \
  --output-format console \
  --verbose
```

### Alias for Frequent Use

Add to your shell profile (`.bashrc`, `.zshrc`):

```bash
alias ai-review="ai-dev review --llm-provider openai --openai-api-key $OPENAI_API_KEY"
alias ai-explain="ai-dev explain --llm-provider openai --openai-api-key $OPENAI_API_KEY"
```

## Troubleshooting

### API Key Issues
- Ensure your API key is valid and has sufficient credits
- Check if you're using the correct provider-specific option

### Permission Issues
- Make sure you have read access to the files you want to analyze
- Check git repository permissions

### Network Issues
- Verify your internet connection
- Check if you need to configure proxy settings
- Ensure firewall allows outbound connections to API endpoints

## Security Notes

- Never commit API keys to version control
- Use environment variables or secure key management for production
- Consider using shorter-lived API keys for better security