Quick Start & Installation

Relevant source files

The following files were used as context for generating this wiki page:

• exports/session-logs/2025-09-13-readme.txt
• CONTRIBUTING.md
• specs/001-create-a-comprehensive/tasks.md
• specs/002-implement-tdd-green/plan.md
• mlx-test/START_HERE.md
• Cargo.toml

caro (also referred to as cmdai in development logs) is a command-line tool built with Rust that converts natural language descriptions into safe, executable POSIX shell commands. It is designed for fast performance, with a single-binary distribution and a safety-first approach, leveraging local LLMs for command generation. This guide provides instructions for installation, first use, and setting up a development environment.

The project emphasizes a local-first approach, with support for multiple backends like MLX for Apple Silicon, as well as remote options like Ollama and vLLM. Safety is a core tenet, with built-in validation to block potentially dangerous commands by default. For developers, the project follows a strict Test-Driven Development (TDD) methodology.

Sources: exports/session-logs/2025-09-13-readme.txt:10-12, CONTRIBUTING.md:19-27, presentation/slides.md:21-29

Installation

There are several methods to install caro, depending on your system and preferences.

Sources: exports/session-logs/2025-09-13-readme.txt:30-44

Recommended Methods

Method	Command	Platform
Homebrew	brew install cmdai	macOS
Cargo	cargo install cmdai	Cross-platform (requires Rust)
Binary Download	Download from GitHub Releases	macOS, Linux, Windows

Sources: exports/session-logs/2025-09-13-readme.txt:33-44

Building from Source

For developers who wish to contribute or use the latest unreleased version, caro can be built directly from the source code.

Prerequisites:

• Rust 1.75+ with Cargo
• Git

Steps:

1. Clone the repository:

   git clone https://github.com/wildcard/caro.git
   cd caro
   

2. Build the release binary:

   cargo build --release
   

The final executable will be located at ./target/release/caro.

Sources: CONTRIBUTING.md:321-332, exports/session-logs/2025-09-13-readme.txt:141-145

The diagram below shows the different installation paths available.

First Run

Once installed, you can start generating commands immediately. The basic syntax is caro [OPTIONS] <PROMPT>.

# Simple command generation
caro "compress all images in current directory"

# Auto-execute the generated command without confirmation
caro --auto "show disk usage of home directory"

# Use a specific model for generation
caro --model "meta-llama/Llama-3.2-8B" "find large log files"

Sources: exports/session-logs/2025-09-13-readme.txt:47-56

The following sequence diagram illustrates a typical command generation flow.

Development Setup

The project follows a strict Test-Driven Development (TDD) workflow. Setting up a local development environment is straightforward.

Sources: CONTRIBUTING.md:316-353

Prerequisites

• Rust 1.75+ with Cargo
• Git for version control
• cargo-watch (recommended for TDD): cargo install cargo-watch

Sources: CONTRIBUTING.md:319-323, specs/002-implement-tdd-green/plan.md:50

Setup and Verification

1. Fork and clone the repository:

   git clone https://github.com/YOUR_USERNAME/caro.git
   cd caro
   

2. Build the project:

   cargo build
   

3. Run the full validation suite: This command checks formatting, lints the code, and runs the test suite. The project uses make for convenience commands.

   make check
   

   Alternatively, you can run the commands manually:

   cargo fmt --check
   cargo clippy -- -D warnings
   cargo test
   

Sources: CONTRIBUTING.md:326-349

TDD Workflow

The development process is centered around a Red-Green-Refactor cycle.

This cycle is often managed using cargo-watch for continuous feedback.

# Start the test watcher in a separate terminal
cargo watch -x test

Sources: CONTRIBUTING.md:355-370

Project Structure

The project is organized into a single binary crate with a modular library structure, ensuring a clear separation of concerns.

caro/
├── src/
│   ├── main.rs          # CLI entry point and main logic
│   ├── lib.rs           # Public library exports
│   ├── safety/          # Command validation and safety checks
│   ├── backends/        # Inference backend implementations (MLX, Ollama, etc.)
│   ├── models/          # Core data structures (CommandRequest, etc.)
│   ├── cli/             # Clap argument parsing and subcommands
│   └── config/          # Configuration management
├── tests/               # Integration and contract tests
├── specs/               # Feature specifications and design docs
└── Cargo.toml         # Project manifest and dependencies

Sources: specs/002-implement-tdd-green/plan.md:104-129, exports/session-logs/2025-09-13-readme.txt:159-173

Key Components

Path	Description
src/main.rs	The main entry point for the CLI application, responsible for parsing arguments and orchestrating the workflow.
src/lib.rs	Exports the core modules as a library, enabling testing and potential integration into other tools.
src/safety/	Contains the SafetyValidator and dangerous command patterns. This is a critical component for the safety-first design.
src/backends/	Defines the CommandGenerator trait and holds implementations for different LLM backends (MLX, Ollama, vLLM, Mock).
src/models/	Defines core data structures like CommandRequest and GeneratedCommand.
src/cli/	Manages CLI argument parsing using clap and defines subcommands.
tests/	Contains all tests, including contract tests that define the public API behavior of each module.

Sources: specs/002-implement-tdd-green/plan.md:104-129, specs/001-create-a-comprehensive/tasks.md:46-77

Configuration

caro supports multiple backends for command generation, which can be configured via CLI flags, environment variables, or a configuration file.

Backend Configuration

The tool supports several backends for LLM inference:

• MLX (Default on macOS): Optimized for Apple Silicon, using Metal for GPU acceleration.
• vLLM: For connecting to a remote, high-performance GPU cluster.
• Ollama: For cross-platform local inference with various models.

You can select a backend using the --backend flag:

# Use Ollama backend
caro --backend ollama "your prompt"

Sources: exports/session-logs/2025-09-13-readme.txt:80-104

Environment Variables

Configuration can also be managed via environment variables.

Variable	Description	Default
CMDAI_BACKEND	Default backend to use (mlx, vllm, ollama).	mlx
CMDAI_MODEL	Default model ID to use.	Auto-detected
CMDAI_ENDPOINT	Default endpoint for remote backends.	http://localhost:8000
HF_HOME	Hugging Face cache directory for models.	~/.cache/huggingface
RUST_LOG	Logging level for the application.	warn

Sources: exports/session-logs/2025-09-13-readme.txt:111-118