Metadata-Version: 2.3
Name: siada-cli
Version: 1.2.0
Summary: Siada CLI is a Ai Pair Programming Tool in terminal
License: Apache-2.0
Requires-Python: >=3.12,<4.0
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Dist: aiohttp (>=3.8.0,<4.0.0)
Requires-Dist: binaryornot (==0.4.4)
Requires-Dist: click (>=8.2.1,<9.0.0)
Requires-Dist: configargparse (>=1.7,<2.0.0)
Requires-Dist: diskcache (==5.6.3)
Requires-Dist: fastapi (>=0.110.0,<1.0.0)
Requires-Dist: gitpython (>=3.1.0,<4.0.0)
Requires-Dist: grep-ast (>=0.9.0,<1.0.0)
Requires-Dist: litellm (>=1.72.6,<2.0.0)
Requires-Dist: mcp (>=1.0.0,<2.0.0)
Requires-Dist: networkx (>=3.5.0,<4.0.0)
Requires-Dist: openai (>=1.102.0)
Requires-Dist: openai-agents (==0.2.9)
Requires-Dist: openhands-aci (==0.3.0)
Requires-Dist: partial-json-parser (>=0.2.1.1.post6,<1.0.0)
Requires-Dist: patch-ng (>=1.18.1,<2.0.0)
Requires-Dist: pexpect (>=4.9.0,<5.0.0)
Requires-Dist: playwright (>=1.40.0,<2.0.0)
Requires-Dist: prompt-toolkit (>=3.0.51,<4.0.0)
Requires-Dist: psutil (>=7.0.0,<8.0.0)
Requires-Dist: pydantic (>=2.6.0,<3.0.0)
Requires-Dist: pydantic-settings (>=2.2.0,<3.0.0)
Requires-Dist: pygments (>=2.19.1,<3.0.0)
Requires-Dist: rich (>=13.0.0,<=14.1.0)
Requires-Dist: shtab (>=1.7,<2.0.0)
Requires-Dist: termcolor (>=3.1.0,<4.0.0)
Requires-Dist: tqdm (>=4.67.1,<5.0.0)
Requires-Dist: trafilatura (>=2.0.0,<3.0.0)
Requires-Dist: uvicorn (>=0.27.0,<1.0.0)
Description-Content-Type: text/markdown

# Siada CLI

**[简体中文](./docs/zh-CN/README_zh.md) | English**

![Siada CLI Screenshot](./docs/assets/siada-cli-screenshot.png)

This repository contains Siada CLI, a command-line AI workflow tool that provides specialized intelligent agents for code development, debugging, and automation tasks.

With Siada CLI you can:

- Fix bugs in large codebases through intelligent analysis and automated solutions.
- Generate new applications and components using specialized frontend and backend agents.
- Automate development workflows through intelligent code generation and testing.
- Execute system commands and interact with development environments.
- Seamlessly support multiple programming languages and frameworks.

## Installation/Update

### System Requirements
- MAC, Linux
- GCC 11+
- uv

### Installation

1. Install uv
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```
2. Install siada-cli
   ```bash
   uv tool install --force --python python3.12 --with pip siada-cli@latest
   ```
   If the siada-cli directory is not present on the PATH, run the follow command to update the shell
   ```bash
   uv tool update-shell
   ```
### Update
   ```bash
   uv tool upgrade siada-cli
   ```
### Uninstall
   ```bash
   uv tool uninstall siada-cli
   ```

## Installation (Developer Mode)

1. **Prerequisites:** Ensure you have [Python 3.12](https://www.python.org/downloads/) or higher and [Poetry](https://python-poetry.org/docs/#installation) installed.

2. **Clone and Install:**
   ```bash
   git clone https://github.com/your-org/siada-agenthub.git
   cd siada-agenthub
   poetry install
   ```

3. **Run CLI:**
   ```bash
   # Method 1: Run with Poetry
   poetry run siada-cli
   
   # Method 2: Activate virtual environment then use (recommended)
   source $(poetry env info --path)/bin/activate
   siada-cli
   ```

## Configuration

### Model Configuration

**Method 1: Default Configuration**
   - The system reads default configuration from `agent_config.yaml` file
   - Current defaults: model `claude-sonnet-4`, provider `openrouter`

   **Method 2: Customize via Configuration File**
   - Regular Users
      - Edit configuration file `~/.siada-cli/conf.yaml`
         ```bash
         # 1. Create configuration file in user home directory
         cd ~
         mkdir -p ~/.siada-cli
         touch ~/.siada-cli/conf.yaml

         # 2. Configuration file content example
         llm_config:
            model: "claude-sonnet-4"          # Change to your desired model
            provider: "openrouter"
         ```
      - Required when using OpenRouter provider
        ```bash
           export OPENROUTER_API_KEY="your_openrouter_key"
        ```
   - Developer Mode
      - Edit the `llm_config` section in `agent_config.yaml` file:
         ```yaml
         llm_config:
            provider: "openrouter"
            model_name: "claude-sonnet-4"     # Change to your desired model
         ```

   **Method 3: Via Environment Variables**
   ```bash
   # Set model
   export SIADA_MODEL="claude-sonnet-4"
   
   # Set provider
   export SIADA_PROVIDER="openrouter"

   # Required when using OpenRouter provider
   export OPENROUTER_API_KEY="your_openrouter_key"
   ```

   **Method 4: Via Command Line Parameters (Highest Priority)**
   ```bash
   # Only change model (keep provider unchanged)
   siada-cli --model claude-sonnet-4
   
   # Change both model and provider
   siada-cli --model gpt-4.1 --provider openrouter
   
   # Only change provider (keep model unchanged)
   siada-cli --provider openrouter
   ```

   > **Important Notes:**
   > - **Complete Priority**: `Command line parameters` > `Environment variables (SIADA_ prefix)` > `Configuration file (agent_config.yaml)`
   > - **Provider Requirements**: When using `openrouter`, must set `OPENROUTER_API_KEY` environment variable

### Agent Configuration (Developer Mode)

Edit `agent_config.yaml` to customize agent behavior:

```yaml
agents:
  bugfix:
    class: "siada.agent_hub.coder.bug_fix_agent.BugFixAgent"
    description: "Specialized agent for code bug fixing"
    enabled: true

llm_config:
  provider: "openrouter"
  model_name: "claude-sonnet-4"
  repo_map_tokens: 8192
  repo_map_mul_no_files: 16
  repo_verbose: true
```

### Environment Variables

Set environment variables to configure behavior:

```bash
# Siada-specific settings (use SIADA_ prefix)
export SIADA_AGENT="bugfix"
export SIADA_MODEL="claude-sonnet-4"
export SIADA_THEME="dark"

# Required when using OpenRouter provider
export OPENROUTER_API_KEY="your_openrouter_key"

# Unset environment variables in current terminal session
unset SIADA_MODEL
```

### Checkpoints Configuration

Siada CLI provides checkpoint tracking functionality to automatically save session states and enable recovery from previous points in your development workflow.

**What are Checkpoints?**
- Automatic snapshots of your session state after significant tool operations
- Includes conversation history, modified files, and git state
- Enables rollback to previous states and comparison between different points in time

**Enable Checkpoint Tracking:**

   **Method 1: Command Line Parameter**
   ```bash
   # Enable checkpoints when starting CLI
   siada-cli --checkpointing
   ```

   **Method 2: Environment Variable**
   ```bash
   # Enable checkpoints globally
   export SIADA_CHECKPOINTING=true
   siada-cli --agent coder
   ```

   **Method 3: Configuration File**
   
   edit `~/.siada-cli/conf.yaml`:
   ```yaml
   checkpoint_config:
     enable: true
   ```

**Checkpoint Usage:**
- Checkpoints are automatically created after tool operations like file edits and command executions
- Use `/restore <checkpoint_file>` to restore to a previous state
- Use `/undo <checkpoint_file>` to undo changes made by a checkpoint, restoring to the state before the checkpoint was created
- Use `/compare <checkpoint_file>` to see differences between current state and a checkpoint

**Storage Location:**
- location: `~/.siada-cli/data/tmp/{project_hash}/checkpoints/session_id/`

### MCP Configuration

Siada CLI integrates MCP (Model Context Protocol) service to provide extended tools and resources for AI agents.

**MCP Configuration File `~/.siada-cli/mcp_config.json`**

   Parameter descriptions:
   - `enabled`: Controls global/individual MCP server switches
   - `type`: Connection type (`stdio`/`http`/`sse`)

   Configuration file example:
   ```json
   {
      "enabled": true,
      "mcpServers": {
         "filesystem": {
            "enabled": true,
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@modelcontextprotocolserver-filesystem", "./"]
         }
      }
   }
   ```

**MCP Slash Commands**

   - `/mcp-server`: List all MCP servers
   - `/mcp-list`: List all MCP servers and their available tools

## Usage Modes

Siada CLI supports two usage modes to meet different usage scenarios:

### Non-Interactive Mode

**Features:**
- One-time execution: Execute a single task and automatically exit
- Stateless: Does not retain session context
- Use cases: Automation scripts, CI/CD pipelines, single task execution

**Usage:**
```bash
# Use --prompt parameter to trigger non-interactive mode
siada-cli --agent bugfix --prompt "Fix login errors in auth.py"

# Combine with other parameters
siada-cli --agent coder --model claude-sonnet-4 --prompt "Create a REST API endpoint"
```

### Interactive Mode

**Features:**
- Continuous conversation: Maintains session state after startup, allows continuous dialogue
- Context memory: AI remembers previous conversation content
- Real-time interaction: Supports slash commands, editor mode, and other advanced features
- Use cases: Exploratory programming, complex tasks, development work requiring multiple rounds of dialogue

**Usage:**
```bash
# Start directly (defaults to interactive mode)
siada-cli --agent coder
```

**Interactive Process:**
```
> Create a user management API
[AI response...]
> Add data validation to this API
[AI response...]
> Write some unit tests
[AI response...]
```

## Command Line Options

```bash
# Use a specific agent
siada-cli --agent coder
# Supports abbreviations
siada-cli -a coder

# Non-interactive mode with a single prompt
siada-cli --prompt "Fix authentication errors in login.py"
# Supports abbreviations
siada-cli -p "Fix authentication errors in login.py"

# Use a different model
siada-cli --model claude-sonnet-4

# Use OpenRouter provider (requires API key setup)
siada-cli --provider openrouter

# Set color theme
siada-cli --theme dark

# Enable verbose output
siada-cli --verbose

# List all available models
siada-cli --list-models
siada-cli --models

# Enable checkpoint tracking (for session recovery)
siada-cli --checkpointing

## Version Check and Update
siada-cli --just-check-update  # Check version only, without executing update
siada-cli --upgrade            # Upgrade to the latest version immediately
siada-cli --check-update       # Check and prompt for updates on startup (enabled by default)

```

## Slash Commands

In the CLI, you can use slash commands for additional functionality:

- `/shell` - Switch to shell mode to execute system commands (type `exit` or `quit` to exit shell mode)
- `/models` - List available AI models
- `/run <command>` or `!<command>` - Execute shell commands
- `/editor` or `/edit` - Open editor for multiline input
- `/multiline-mode` - Toggle multiline mode (changes behavior of Enter and Meta+Enter keys)
  - Enter key for line break
  - Meta+Enter key to end multiline mode and send content to the model
- `/init [--force]` - Analyze the project and create a tailored siada.md file
- `/restore <checkpoint_file>` - Restore session state from a checkpoint file (requires checkpoint tracking enabled)
- `/undo <checkpoint_file>` - Undo changes made by a checkpoint, restoring to the state before the checkpoint was created (requires checkpoint tracking enabled)
- `/compare <checkpoint_file>` - Compare current state with a checkpoint file to see differences
- `/memory-refresh` - Refresh user memory content from siada.md file
- `/memory-status` - Display current user memory status (file info, size, loaded status)
- `/status` - Display current session status (model, agent, session ID, and workspace)
- `/exit` or `/quit` - Exit the application

### Shell Mode Usage Guide

Siada CLI provides two ways to execute system commands:

#### Method 1: Use `/shell` to switch to shell mode
Switch to persistent shell mode where you can continuously execute multiple system commands:

```bash
> /shell
# After entering shell mode, you can execute multiple commands
ls -la
cd my-project
npm install
git status
# Use exit or quit to exit shell mode
exit
```

#### Method 2: Use `!` prefix to execute commands directly
Execute single system commands directly in interactive mode without switching modes:

```bash
> !ls -la
> !git status
> !npm run dev
```

Differences between the two methods:
- **`/shell`**: Suitable for scenarios requiring continuous execution of multiple system commands, switch once and use persistently
- **`!<command>`**: Suitable for occasionally executing single system commands, returns to AI conversation mode immediately after execution

## Agent Types

### Bug Fix Agent (`--agent bugfix` / `-a bugfix` / `--bugfix`) 
> **Only supports non-interactive mode!**

Specialized for identifying, analyzing, and fixing bugs in codebases. Provides detailed analysis and automated fix suggestions.

### Code Generation Agent (`--agent coder` / `-a coder` / `--coder`)
General-purpose code development agent for creating new features, refactoring code, and implementing functionality in various programming languages.

### Frontend Generation Agent (`--agent fegen` / `-a fegen` / `--fegen`)
Focused on frontend development tasks, including React components, CSS styling, and user interface implementation.

## Examples

### Activate Virtual Environment (Developer Mode Only)
First, enter the siada-agenthub project directory and activate the virtual environment:

```bash
# Enter project directory
cd ~/path/to/siada-agenthub

# Activate virtual environment (recommended method)
source $(poetry env info --path)/bin/activate

# Or use Poetry run (no need to activate environment)
# poetry run siada-cli
```

### Usage Examples

After activating the environment, you can choose between interactive mode or non-interactive mode to interact with AI agents.

**Interactive Mode:**

```bash
# Enter project directory
cd my-project/

# Start interactive mode
siada-cli --agent coder

# Then you can input prompts in the interactive interface
> Create a REST API server with user authentication using FastAPI
# AI will respond and you can continue the conversation...
> Add logging functionality to this API
```

**Non-Interactive Mode (One-time execution):**

```bash
# Execute a single task and exit (uses coder agent by default)
siada-cli --prompt "Create a user registration API"

# Specify a specific agent to execute tasks
siada-cli --agent bugfix --prompt "Fix authentication errors in login.py"
siada-cli --agent fegen --prompt "Create a responsive navigation bar component using React and Tailwind CSS"
```

**Exit Virtual Environment (Developer Mode Only):**

```bash
# Exit virtual environment after use
deactivate
```

## Common Tasks

### Debug and Fix Code Issues

```text
> Analyze this error message and suggest a fix: [paste error]
```

```text
> Help me reproduce this intermittent bug that occurs during high load
```

### Code Generation and Development

```text
> Implement a caching layer for the database queries in this service
```

```text
> Refactor this monolithic function into smaller, more maintainable pieces
```

### Frontend Development

```text
> Create a responsive dashboard layout with sidebar navigation
```

```text
> Add form validation to the user registration form
```

## Troubleshooting

### Common Issues

**Command not found:**
If running `siada-cli` directly shows command not found:
- This is normal behavior in developer mode as the command is installed in the virtual environment
- Refer to examples to activate the virtual environment

**Model API errors:**
- Check your internet connection
- If using OpenRouter provider, ensure API key is set correctly
- If using OpenRouter provider, verify your account has sufficient credits

**Installation issues:**
- Ensure you have Python 3.12+ installed
- Install Poetry using the official installation method
- Try removing `poetry.lock` and re-running `poetry install`

**Agent not working:**
- Check if the agent is enabled in `agent_config.yaml`
- Verify the agent class path is correct
- Use `--verbose` flag to see detailed output

For more detailed troubleshooting, check logs and use the `--verbose` flag for additional debug information.

## Contributing

We welcome contributions to Siada CLI! Whether you want to fix bugs, add new features, improve documentation, or suggest enhancements, your contributions are greatly appreciated.

To get started with contributing, please read our [Contributing Guide](./docs/CONTRIBUTING.md) which includes:

- Our project vision and development goals
- Project directory structure and development guidelines
- Pull request guidelines and best practices
- Code organization principles

Before submitting any changes, please make sure to check our issue tracker and follow the contribution workflow outlined in the guide.

## Acknowledgements

Siada CLI is built upon the foundation of numerous open source projects, and we extend our deepest respect and gratitude to their contributors.

Special thanks to the [OpenAI Agent SDK](https://github.com/openai/openai-agent-sdk) for providing the foundational framework that powers our intelligent agent capabilities.

For a complete list of open source projects and licenses used in Siada CLI, please see our [CREDITS.md](./docs/CREDITS.md) file.

## License

Distributed under the Apache-2.0 License. See [`LICENSE`](LICENSE) for more information.

## DISCLAIMERS
See [disclaimers.md](./disclaimers.md)

----
<div align="center">
Built with ❤️ by Li Auto Code Intelligence Team and the open source community
</div>

