Getting Started

Prerequisites

You need at least one supported AI CLI installed on the system where your app runs:

CLI	Install
Claude Code	`npm install -g @anthropic-ai/claude-code`
Codex	`npm install -g @openai/codex`
Gemini CLI	`npm install -g @google/gemini-cli`

Installation

As a Rust library

Add to your Cargo.toml:

[dependencies]
cli-agents = "0.2"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

As a CLI tool

# Via npm (recommended — prebuilt binaries, no Rust toolchain needed)
npm install -g @cueframe/cli-agents

# Via cargo
cargo install cli-agents --features cli

# Or download a binary from GitHub Releases
# https://github.com/skoppisetty/cli-agents-rs/releases

Basic usage

The core API is a single function: run(). Pass it a RunOptions struct and an optional event callback:

use cli_agents::{run, RunOptions, StreamEvent, CliName};
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let opts = RunOptions {
        cli: Some(CliName::Claude),
        task: "What is 2+2?".into(),
        skip_permissions: true,
        ..Default::default()
    };

    let handle = run(opts, Some(Arc::new(|event: StreamEvent| {
        match &event {
            StreamEvent::TextDelta { text } => print!("{text}"),
            StreamEvent::Done { result } => println!("\nDone: {:?}", result.success),
            _ => {}
        }
    })));

    let result = handle.result.await.unwrap().unwrap();
    println!("Success: {}", result.success);
}

Auto-discovery

Omit the cli field to auto-discover the first available agent. The priority order is Claude → Codex → Gemini:

let opts = RunOptions {
    task: "Summarize this project.".into(),
    cwd: Some("./my-project".into()),
    ..Default::default()
};
let handle = run(opts, None);

You can also query which CLIs are installed:

use cli_agents::discovery::{discover_all, discover_first};

let all = discover_all().await;
for (name, path) in &all {
    println!("{name}: {path}");
}

Cancellation

The RunHandle includes a CancellationToken for aborting a run:

let handle = run(opts, None);

let cancel = handle.cancel.clone();
tokio::spawn(async move {
    tokio::signal::ctrl_c().await.ok();
    cancel.cancel();
});

let result = handle.result.await.unwrap().unwrap();
// result.success == false when cancelled

Use cases

Desktop apps (Tauri)

Build rich agentic UIs that leverage whatever AI CLI the user has installed. RunOptions is serde-compatible, so frontends pass config as JSON and receive StreamEvents back via Tauri events.

Dev tools and CI

Build custom coding agents, review bots, or CI automation that piggyback on existing CLI installations — no API keys needed.

Multi-agent orchestration

Run multiple agents concurrently or route tasks to different providers based on availability.

Getting Started

On this page