Quick Start

Quick Start

This guide will get you productive with caro in just a few minutes.

Installation

Quick Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/wildcard/caro/main/install.sh | bash

The install script will:

• Install via Cargo if Rust is available (with MLX optimization on Apple Silicon)
• Otherwise download a pre-built binary for your platform
• Verify SHA256 checksums for security
• Configure your PATH automatically

Cargo

# Standard install
cargo install caro

# Apple Silicon with MLX GPU acceleration
cargo install caro --features embedded-mlx

Pre-built Binary

# Download for your platform from GitHub Releases
curl -fsSL https://github.com/wildcard/caro/releases/latest/download/caro-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m) -o caro
chmod +x caro
sudo mv caro /usr/local/bin/

Verify installation:

caro --version
# Output: caro 1.0.3

Basic Usage

Simply describe what you want to do in natural language:

caro "your natural language description"

1. Type your command description in quotes
2. Review the generated command caro shows you
3. Confirm execution by typing y or copy the command

Interactive Confirmation

When you run a command, caro shows the generated command and asks for confirmation:

$ caro "list all PDF files in Downloads folder larger than 10MB"

Command:
  find ~/Downloads -name "*.pdf" -size +10M -ls

? Execute this command? (y/n) y

This interactive flow ensures you always review commands before execution.

Common Examples

File Operations

$ caro "find all python files"
Command:
  find . -name "*.py"

$ caro "find files larger than 100MB"
Command:
  find . -size +100M

$ caro "find files modified in the last 24 hours"
Command:
  find . -mtime 0

Text Search

$ caro "search for TODO in all source files"
Command:
  grep -rn "TODO" --include="*.py" --include="*.js" --include="*.rs"

$ caro "find lines containing error in log files"
Command:
  grep -i "error" *.log

$ caro "count occurrences of function in all rust files"
Command:
  grep -c "fn " *.rs

System Information

$ caro "show disk usage"
Command:
  df -h

$ caro "show running processes sorted by memory"
Command:
  ps aux --sort=-%mem | head -20

$ caro "show network connections"
Command:
  netstat -an | grep ESTABLISHED

Directory Operations

$ caro "show directory size"
Command:
  du -sh .

$ caro "list directories sorted by size"
Command:
  du -sh */ | sort -hr

$ caro "create directory structure for a rust project"
Command:
  mkdir -p src/{bin,lib} tests docs

Understanding the Output

caro provides clear, colored output:

$ caro "find all rust files modified today"

Command:
  find . -name "*.rs" -mtime 0

? Execute this command? (y/n)

Element	Description
Command	The shell command caro generated for your request
Confirmation	Interactive prompt to execute or decline

When a command is potentially dangerous, caro will show a warning and require explicit confirmation before proceeding.

Platform-Aware Generation

caro automatically detects your environment and generates platform-appropriate commands:

• Operating system (macOS, Linux, Windows)
• Architecture (x86_64, ARM64/Apple Silicon)
• Shell type (bash, zsh, fish)
• Available commands on your system

This means the same natural language prompt produces the correct command for your platform.

Safety Features

caro automatically validates commands for safety:

# This will be blocked
$ caro "delete everything"

⚠️  Command blocked: Potentially dangerous pattern detected
    Pattern: rm -rf /
    Risk: Critical

# Safe alternative suggested
Tip: Try "caro 'delete files in current directory'" for a safer approach

Caution

Never blindly execute generated commands. Always review them first, especially when dealing with file operations.

Command Execution Options

Interactive Confirmation (Default)

The default behavior is to show the command and ask for confirmation:

$ caro "find large log files"
Command:
  find . -name "*.log" -size +10M

? Execute this command? (y/n) y
# Command executes...

Auto-Confirmation with --confirm

For scripting or when you trust the command, use --confirm (or -y) to skip the confirmation prompt:

# Skip confirmation prompt
caro --confirm "show current date"

# Short form
caro -y "list files"

Caution

Using --confirm skips the confirmation prompt. Only use this for well-understood operations.

Copy Without Execution

Press n at the confirmation prompt to decline execution - the command remains visible for you to copy:

$ caro "find large log files"
Command:
  find . -name "*.log" -size +10M

? Execute this command? (y/n) n
# Command not executed - copy it manually if desired

Tips for Better Results

Be Specific

More detail = better results. Instead of “find files”, try “find python files modified this week”.

Use Constraints

Add limits like “in current directory” or “excluding node_modules”.

Describe the Goal

Say what you want to achieve, not how. “compress images for web” beats “run imagemagick”.

Iterate

If the first result isn’t perfect, refine your description and try again.

Good vs. Bad Prompts

Bad Prompt	Good Prompt
”files"	"find all PDF files in the downloads folder"
"search"	"search for ‘TODO’ comments in python files"
"compress"	"compress all jpg files to 80% quality"
"ports"	"show which process is using port 8080”

Workflow Examples

Development Workflow

# Find uncommitted changes
$ caro "show git status with diff stats"
Command:
  git status -sb && git diff --stat

# Find TODO comments
$ caro "find TODO comments in src directory"
Command:
  grep -rn "TODO" src/

# Count lines of code
$ caro "count lines of rust code"
Command:
  find . -name "*.rs" -exec wc -l {} + | tail -1

System Administration

# Check system health
$ caro "show system uptime and load average"
Command:
  uptime

# Find large files
$ caro "find files larger than 1GB"
Command:
  find . -size +1G 2>/dev/null

# Check disk space
$ caro "show disk usage by directory sorted by size"
Command:
  du -sh */ | sort -hr

Data Processing

# CSV operations
$ caro "show first 10 lines of data.csv"
Command:
  head -10 data.csv

$ caro "count unique values in second column of data.csv"
Command:
  cut -d',' -f2 data.csv | sort | uniq -c | sort -rn

# JSON processing
$ caro "extract name field from config.json"
Command:
  jq '.name' config.json

CLI Options

Option	Short	Description
--confirm	-y	Auto-confirm dangerous commands without prompting
--shell <SHELL>	-s	Target shell (bash, zsh, fish, sh)
--output <FORMAT>	-o	Output format (json, yaml, plain)
--safety <LEVEL>		Safety level (strict, moderate, permissive)
--verbose	-v	Enable verbose output with timing
--config <FILE>	-c	Custom configuration file

Example with options:

# Use a specific shell
caro --shell zsh "find python files"

# JSON output for scripting
caro --output json "show disk usage"

# Verbose mode for debugging
caro --verbose "search for errors in logs"

Next Steps

Now that you know the basics:

• macOS Setup - Enable GPU acceleration for faster inference
• Safety Validation - Learn about the safety system
• Configuration - Customize caro’s behavior
• Backend Options - Explore different inference backends