Basic CLI Usage
Relevant source files
The following files were used as context for generating this wiki page:
The caro (also referred to as cmdai) command-line interface is the primary way for users to interact with the system. It is designed to convert natural language prompts into safe, executable POSIX shell commands. The CLI prioritizes safety through built-in validation and user confirmation, while providing a fast, local-first experience. It supports multiple LLM backends and offers various options for customizing command generation.
The core functionality revolves around taking a user's text prompt, generating a corresponding shell command, validating it for safety, and then, with user permission, executing it. The CLI is architected to be a single, self-contained binary with no external dependencies for its core operation.
Sources: exports/session-logs/2025-09-13-readme.txt, presentation/slides.md
Command Generation Workflow
The primary use of caro is to generate a shell command from a natural language prompt. The process is initiated by running the caro command followed by the prompt as a string.
Basic Syntax
caro [OPTIONS] <PROMPT>
For example:
$ caro "list all PDF files in Downloads folder larger than 10MB"
Generated command:
find ~/Downloads -name "*.pdf" -size +10M -ls
Execute this command? (y/N) y
This simple interaction triggers a multi-step internal workflow designed to ensure safety and correctness before any command is executed.
Sources: exports/session-logs/2025-09-13-readme.txt
High-Level Data Flow
The following diagram illustrates the command generation and validation pipeline within the caro CLI.
This diagram shows the flow from the user's natural language prompt through safety validation, risk assessment, command generation via a selected backend, POSIX validation, and finally to user confirmation before execution.
Sources: presentation/slides.md
CLI Options
The behavior of the caro command can be modified using various command-line options. These flags allow users to control the inference backend, execution behavior, and other operational parameters.
| Option | Description | Default |
|---|---|---|
--backend | Inference backend (mlx, vllm, ollama) | mlx |
--model | Specific model ID or path | Auto-detected |
--endpoint | Remote backend endpoint | http://localhost:8000 |
--cache-dir | Model cache directory | ~/.cache/huggingface/hub |
--auto | Execute without confirmation | false |
--allow-dangerous | Allow potentially dangerous commands | false |
--verbose | Enable verbose logging | false |
--context | Include N previous commands | 0 |
--goal | Multi-step goal completion mode | false |
Sources: exports/session-logs/2025-09-13-readme.txt
Subcommands
In addition to direct command generation, caro provides several subcommands for managing its configuration and components. These are planned as part of the core CLI interface.
| Subcommand | Description |
|---|---|
config | Manage user configuration settings. |
models | Manage local and remote models. |
backends | Manage and inspect available inference backends. |
history | Manage and view command history. |
The subcommand structure is designed to be modular, allowing for clear separation of concerns within the CLI.
This diagram shows the main generate command and the planned subcommands for managing different aspects of the tool.
Sources: specs/001-create-a-comprehensive/tasks.md:33-37
Usage Examples
Basic Operations
File Operations
# Find and organize files
caro "move all screenshots from Desktop to Pictures/Screenshots"
# Batch rename files
caro "rename all .jpeg files to .jpg in current directory"
# Clean up empty directories
caro "delete empty directories recursively"
System Information
# Check disk usage
caro "show which folders are taking up the most space"
# Monitor processes
caro "find processes using more than 1GB of RAM"
# Check network ports
caro "check if port 3000 is in use"
Development Tasks
# Git operations
caro "create a new branch called feature-auth and switch to it"
# Run tests on modified files
caro "run tests only for files modified in the last commit"
# Docker operations
caro "stop all running containers and remove unused images"
Sources: exports/session-logs/2025-09-13-readme.txt
Advanced Usage
Context-Aware Commands
The --context flag allows the tool to consider previous commands, enabling follow-up requests.
caro --context 3 "undo that last operation"
Cross-Platform Generation
Users can set a target platform to generate commands for a different OS.
# Configure target OS to Linux
caro config set platform.target_os linux
# Generate a command for Linux while on macOS
$ caro "list files sorted by size"
⚠️ Cross-Platform Mode: macOS → Linux (GNU)
Command: ls -lh --sort=size
Explanation: Generated for Linux/GNU systems
✓ Validated against GNU coreutils ls 9.0
This feature is particularly useful for DevOps engineers and developers working in multi-platform environments.
Sources: exports/session-logs/2025-09-13-readme.txt, specs/006-intelligent-prompt-generation/spec.md
Interactive Workflows
caro is designed to be interactive, especially when dealing with ambiguity or potential risks.
Command Confirmation
By default, caro requires explicit user confirmation before executing any generated command. This is a core safety feature. The --auto flag can be used to bypass this confirmation for trusted commands. The confirmation flow is a key part of the CLI interface contract.
Sources: exports/session-logs/2025-09-13-readme.txt, exports/session-logs/2025-10-01-check-the-pr.txt
Ambiguity Clarification
When a user's prompt is too vague, caro can initiate a clarification dialogue to refine the request. This avoids guesswork and results in a more accurate and safer command.
Example Clarification Flow:
$ caro "clean up disk space"
🤔 Clarification needed (ambiguity: 0.82)
1. Which location?
a) Home directory (~)
b) Specific folder
c) System-wide (requires sudo)
2. What criteria?
a) Large files (>100MB)
b) Old files (>30 days)
c) Duplicate files
3. Action preference?
a) List only (safe)
b) Move to trash
c) Permanent delete
Your choice (1a, 2a, 3a): 1a 2a 3a
Command: find ~ -type f -size +100M -mtime +30 -ls
Explanation: Lists large, old files in home directory
✓ Confidence: 0.92
The following sequence diagram illustrates this interactive process.
This workflow ensures that the final command accurately reflects the user's specific intent, significantly improving safety and utility.
Sources: specs/006-intelligent-prompt-generation/spec.md
Summary
The caro CLI provides a powerful yet user-friendly interface for generating shell commands from natural language. Its basic usage is a simple, single-line command, but it is backed by a robust set of options, subcommands, and interactive workflows. Key features like the default confirmation prompt and the ambiguity clarification process are central to its safety-first design philosophy, ensuring that users remain in control while benefiting from AI-powered command generation.
Sources: CONTRIBUTING.md, specs/006-intelligent-prompt-generation/spec.md