---
title: "CLI Reference"
description: "Complete command-line reference for Caro"
url: "https://caro.sh/docs/cli"
markdown_url: "https://caro.sh/docs/cli.md"
lang: "en"
type: "website"
image: "https://caro.sh/og/docs/cli.png"
---

# CLI Reference

Complete reference for all Caro command-line options and subcommands.

## Basic Usage

```
caro [OPTIONS] <PROMPT>
caro <SUBCOMMAND>
```

## Subcommands

### init

Run the interactive setup wizard to configure Caro.

```
caro init [OPTIONS]

Options:
  --minimal     Use minimal ASCII art banner
  -f, --force   Force reconfiguration even if already set up
```

## Options

### -s, --shell \<SHELL>

Target shell type for command generation.

```
caro --shell bash "list files"
caro -s zsh "find large files"
```

Valid values: `bash`, `zsh`, `fish`, `sh`, `powershell`, `cmd`

### --safety \<LEVEL>

Safety level for command validation.

```
caro --safety strict "delete old files"
```

Valid values: `strict`, `moderate`, `permissive`

### -o, --output \<FORMAT>

Output format for the generated command.

```
caro -o json "list files"
caro --output yaml "show disk usage"
```

Valid values: `plain` (default), `json`, `yaml`

### -y, --confirm

Auto-confirm dangerous commands without prompting.

```
caro -y "remove temp files"
```

**Warning** Use with caution. Only use when you're certain about the command.

### -v, --verbose

Enable verbose output with timing and debug information.

```
caro -v "find Python files"
```

### -c, --config-file \<PATH>

Path to a custom configuration file.

```
caro -c /path/to/config.toml "list files"
```

### --show-config

Show current configuration and exit.

```
caro --show-config
```

### -x, --execute

Execute the generated command after validation.

```
caro -x "show current date"
```

### --dry-run

Show execution plan without running the command.

```
caro --dry-run "delete all log files"
```

### -i, --interactive

Interactive mode with step-by-step confirmation.

```
caro -i "set up Python virtual environment"
```

### -h, --help

Print help information.

```
caro --help
caro init --help
```

### -V, --version

Print version information.

```
caro --version
```

## Examples

### Basic Commands

```
# Generate a command
caro "list all Python files"

# With specific shell
caro --shell bash "find large files"

# With JSON output
caro -o json "show disk usage"
```

### Safety Options

```
# Strict safety mode
caro --safety strict "clean up old files"

# Preview dangerous commands
caro --dry-run "remove all temp files"

# Auto-confirm (use carefully!)
caro -y "delete cache"
```

### Execution Options

```
# Execute immediately
caro -x "show current directory"

# Interactive mode
caro -i "set up new project"

# Verbose output
caro -v "compile source code"
```

### Configuration

```
# Run setup wizard
caro init

# Force reconfiguration
caro init --force

# Use custom config
caro -c ~/my-config.toml "list files"

# Show current config
caro --show-config
```

## Exit Codes

- `0` - Success
- `1` - Error (configuration, validation, or execution)

## Environment Variables

See [Configuration](https://caro.sh/docs/configuration) for available environment variables.