iFlow CLI SDK for Rust

A powerful Rust SDK for interacting with iFlow using the Agent Client Protocol (ACP). This SDK provides both simple query functions and full bidirectional client for complex interactions.

Features

• 🚀 Automatic Process Management - SDK automatically starts and manages iFlow process
• 🔌 Stdio Communication - Communicate with iFlow via stdio
• 🔌 WebSocket Communication - Communicate with iFlow via WebSocket for better performance and reliability
• 🔄 Bidirectional Communication - Real-time streaming messages and responses
• 🛠️ Tool Call Management - Fine-grained permission control for tool execution
• 📋 Task Planning - Receive and process structured task plans
• 🔍 Raw Data Access - Debug and inspect protocol-level messages
• ⚡ Async/Await Support - Modern async Rust with full type safety

TODO

• 🤖 Sub-agent Support - Track and manage multiple AI agents via agent_id

ROADMAP.md

Installation

Add this to your Cargo.toml:

[dependencies]
iflow-cli-sdk-rust = "0.1.0"

Or install directly from the crate.io or GitHub repository:

cargo add iflow-cli-sdk-rust
# or
cargo add --git https://github.com/vibe-ideas/iflow-cli-sdk-rust

Quick Start

Simple Query

use iflow_cli_sdk_rust::query;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let response = query("What is 2 + 2?").await?;
    println!("{}", response); // "4"
    Ok(())
}

Message Types

The SDK handles various message types from iFlow:

• Message::Assistant { content } - AI assistant responses
• Message::ToolCall { id, name, status } - Tool execution requests
• Message::Plan { entries } - Structured task plans
• Message::TaskFinish { reason } - Task completion signals
• Message::Error { code, message } - Error notifications
• Message::User { content } - User message echoes

Examples

Run the examples:

# Simple query example
cargo run --example query

# use WebSocket communication instead of stdio.
cargo run --example websocket_client

# MCP Servers
cargo run --example mcp_example

Architecture

The SDK is organized into several modules:

• client - Main IFlowClient implementation with stdio communication
• types - Type definitions and message structures
• process_manager - iFlow process lifecycle management
• query - Convenience functions for simple queries
• error - Error types and handling
• logger - Message logging functionality

Requirements

• Rust 1.90+
• iFlow CLI installed with --experimental-acp support (or use auto-start feature)

Development

Building

cargo build

Testing

cargo test

# Run specific test suites
cargo test --test websocket_config_tests
cargo test --test websocket_integration_tests

# e2e tests
cargo test --test e2e_tests -- --nocapture

Running with logging

RUST_LOG=debug cargo run --example basic_client

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Who is using this SDK?

• iflow-cli-action: Automate software development tasks within your GitHub repositories with iFlow CLI.