# iFlow CLI SDK for Rust
A powerful Rust SDK for interacting with iFlow using the [Agent Client Protocol (ACP)](https://github.com/agentclientprotocol/agent-client-protocol). This SDK provides both simple query functions and full bidirectional client for complex interactions.
[](https://github.com/vibe-ideas/iflow-cli-sdk-rust/actions/workflows/ci.yml) [](https://codecov.io/gh/vibe-ideas/iflow-cli-sdk-rust) [](https://crates.io/crates/iflow-cli-sdk-rust) [](https://deepwiki.com/vibe-ideas/iflow-cli-sdk-rust)
<!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->
## 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](ROADMAP.md)
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
iflow-cli-sdk-rust = "0.1.0"
```
Or install directly from the crate.io or GitHub repository:
```bash
cargo add iflow-cli-sdk-rust
# or
cargo add --git https://github.com/vibe-ideas/iflow-cli-sdk-rust
```
## Quick Start
### Simple Query
```rust
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](./examples):
```bash
# 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
```bash
cargo build
```
### Testing
```bash
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
```bash
RUST_LOG=debug cargo run --example basic_client
```
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Who is using this SDK?
- [iflow-cli-action](https://github.com/iflow-ai/iflow-cli-action): Automate software development tasks within your GitHub repositories with iFlow CLI.