# Refinire CLI - Environment Setup Wizard

The Refinire CLI provides an interactive environment variable template generator that helps you quickly set up your development environment with the LLM providers and features you need.

## Installation

Install Refinire with CLI dependencies:

```bash
pip install "refinire[cli]"
```

Or install with all features:

```bash
pip install "refinire[all]"
```

## Usage

Run the interactive setup wizard:

```bash
refinire-setup
```

The wizard will guide you through:

1. **LLM Provider Selection** - Choose from OpenAI, Anthropic, Google, OpenRouter, Groq, Ollama, or LM Studio
2. **Feature Selection** - Enable tracing, agent configuration, or development features
3. **Template Generation** - Create a customized `.env` template file

## Features

### 🎯 Interactive Provider Selection

The CLI presents a beautiful table of available LLM providers with descriptions:

```
Available LLM Providers
┌────┬────────────┬──────────────────────────────────────┐
│ ID │ Provider   │ Description                          │
├────┼────────────┼──────────────────────────────────────┤
│ 1  │ OpenAI     │ OpenAI GPT models                    │
│ 2  │ Anthropic  │ Claude models                        │
│ 3  │ Google     │ Gemini models                        │
│ 4  │ OpenRouter │ Multiple providers via OpenRouter    │
│ 5  │ Groq       │ Fast inference models                │
│ 6  │ Ollama     │ Local models                         │
│ 7  │ LMStudio   │ Local LM Studio models               │
└────┴────────────┴──────────────────────────────────────┘
```

### 🚀 Feature Configuration

Enable additional features based on your needs:

- **Tracing**: OpenTelemetry integration for observability
- **Agents**: Multi-model agent configuration with fallback hierarchy
- **Development**: Debug mode and development tools

### 📋 Smart Template Generation

The CLI generates optimized `.env` template files with:

- **Provider-specific variables** - Only includes variables for selected providers
- **Feature-specific settings** - Adds configuration for enabled features
- **Fallback hierarchy** - Supports task-specific model overrides
- **Documentation** - Includes comments and usage instructions

## Example Output

A typical generated template might look like:

```bash
# Refinire Environment Variables
# Generated by Refinire CLI

# =============================================================================
# LLM Provider Configuration
# =============================================================================

# OpenAI Configuration
OPENAI_API_KEY=

# Anthropic Configuration
ANTHROPIC_API_KEY=

# Agent Configuration
REFINIRE_DEFAULT_LLM_MODEL=gpt-4o-mini
REFINIRE_DEFAULT_GENERATION_LLM_MODEL=gpt-4o-mini
REFINIRE_DEFAULT_ROUTING_LLM_MODEL=gpt-4o-mini
REFINIRE_DEFAULT_EVALUATION_LLM_MODEL=gpt-4o-mini
REFINIRE_DEFAULT_TEMPERATURE=0.7
REFINIRE_DEFAULT_MAX_TOKENS=2048

# OpenTelemetry Tracing
REFINIRE_TRACE_OTLP_ENDPOINT=
REFINIRE_TRACE_SERVICE_NAME=refinire-agent
REFINIRE_TRACE_RESOURCE_ATTRIBUTES=
```

## Model Selection Priority

The CLI configures a flexible model selection hierarchy:

1. **Direct specification** (highest priority) - Explicitly specified in code
2. **Task-specific models** - `REFINIRE_DEFAULT_GENERATION_LLM_MODEL`, etc.
3. **Default fallback** - `REFINIRE_DEFAULT_LLM_MODEL` (lowest priority)

This allows you to:
- Use different models for different tasks (generation vs. evaluation)
- Override specific tasks while keeping defaults for others
- Maintain consistency across your application

## Advanced Usage

### Programmatic Usage

You can also use the CLI components programmatically:

```python
from refinire.cli import RefinireTemplateGenerator

# Create generator
generator = RefinireTemplateGenerator()

# Generate template content
providers = ["OpenAI", "Anthropic"]
features = ["Agents", "Tracing"]
content = generator.generate_template_content(providers, features)

# Save to file
generator.save_template(content, ".env.example")
```

### OneEnv Integration

Refinire registers its templates with OneEnv through entry points in `pyproject.toml`:

```toml
[project.entry-points."oneenv.templates"]
core = "refinire.templates:core_template"
tracing = "refinire.templates:tracing_template"
agents = "refinire.templates:agents_template" 
development = "refinire.templates:development_template"
```

This enables:
- **Automatic discovery** by OneEnv tools
- **Template reuse** across different projects
- **Standardized configuration** management

## Next Steps

After running the CLI:

1. **Copy the template**: `cp .env.example .env`
2. **Fill in your API keys**: Add your actual API keys and configuration values
3. **Start coding**: Use Refinire with your configured providers!

## Troubleshooting

### Missing Dependencies

If you see import errors, install CLI dependencies:

```bash
pip install "refinire[cli]"
```

### OneEnv Integration Issues

The CLI includes fallback functionality if OneEnv APIs are unavailable. You'll see a warning message but the tool will continue to work.

### Template Generation Errors

If template generation fails, the CLI will:
- Display the error message
- Fall back to built-in template generation
- Continue with the setup process

## Contributing

To contribute to the CLI:

1. Install development dependencies: `pip install "refinire[dev]"`
2. Run tests: `pytest tests/test_cli.py`
3. Add new features to `src/refinire/cli.py`
4. Update documentation in `docs/cli.md`

The CLI is built with:
- **Rich** for beautiful terminal interfaces
- **OneEnv** for template management
- **Pytest** for testing