# CLI API

Command-line interface implementation for SousChef.

## Overview

The `souschef.cli` module provides a command-line interface for migration and upgrade workflows using the Click framework. All commands are accessible via the `souschef-cli` entry point.

---

## CLI Commands

See the [CLI Usage Guide](../user-guide/cli-usage.md) for complete documentation of all available commands with examples.

---

## Usage Examples

### Basic Command Usage

```bash
# Parse a recipe
souschef-cli recipe recipes/default.rb

# Convert with JSON output
souschef-cli recipe recipes/default.rb --format json

# Convert to playbook
souschef-cli convert-recipe recipes/default.rb > playbook.yml
```

### Piping Commands

```bash
# Parse and filter
souschef-cli recipe recipes/default.rb | grep "package"

# Convert and validate
souschef-cli convert-recipe recipes/default.rb | ansible-playbook --syntax-check

# Batch processing
find cookbooks/ -name "*.rb" | xargs -I {} souschef-cli recipe {}
```

### Output Formats

```bash
# Text output (default)
souschef-cli recipe recipes/default.rb --format text

# JSON for programmatic use
souschef-cli recipe recipes/default.rb --format json | jq '.resources'

# YAML output
souschef-cli recipe recipes/default.rb --format yaml
```

---

## Click Integration

SousChef uses Click for CLI implementation:

```python
import click
from souschef.parsers.recipe import RecipeParser

@click.command()
@click.argument('recipe_path', type=click.Path(exists=True))
@click.option('--format', type=click.Choice(['text', 'json', 'yaml']), default='text')
def recipe(recipe_path: str, format: str) -> None:
    """Parse a Chef recipe."""
    parser = RecipeParser(recipe_path)
    result = parser.parse()
    click.echo(format_output(result, format))
```

Benefits:
- Automatic help generation
- Type validation
- Shell completion support
- Click context management

---

## Error Handling

CLI commands handle errors consistently:

```python
try:
    result = parse_recipe(recipe_path)
    click.echo(result)
except FileNotFoundError:
    click.echo(f"Error: File not found: {recipe_path}", err=True)
    sys.exit(1)
except Exception as e:
    click.echo(f"Error: {e}", err=True)
    sys.exit(1)
```

---

## Shell Completion

Enable shell completion for faster CLI usage:

```bash
# Bash
eval "$(_SOUSCHEF_CLI_COMPLETE=bash_source souschef-cli)"

# Zsh
eval "$(_SOUSCHEF_CLI_COMPLETE=zsh_source souschef-cli)"

# Fish
eval (env _SOUSCHEF_CLI_COMPLETE=fish_source souschef-cli)
```

Add to shell rc file for persistence:

```bash
echo 'eval "$(_SOUSCHEF_CLI_COMPLETE=bash_source souschef-cli)"' >> ~/.bashrc
```

---

## See Also

- **[Server API](server.md)** - MCP server implementation
- **[Parsers API](parsers.md)** - Parsing modules
- **[CLI Usage Guide](../user-guide/cli-usage.md)** - User documentation
- **[Click Documentation](https://click.palletsprojects.com/)** - CLI framework
