Metadata-Version: 2.4
Name: cursor-cli
Version: 0.1.2
Summary: A wrapper for cursor-agent with formatted output support
Author: AITS Team
License: MIT
Keywords: cursor,agent,cli,wrapper
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: author
Dynamic: requires-python

# Cursor CLI

A Python wrapper for `cursor-agent` with enhanced output formatting support.

## Installation

### From PyPI

```bash
pip install cursor-cli
```

### From source

```bash
cd cursor_cli
pip install -e .
```

### Or run directly as a module

```bash
python -m cursor_cli [args...]
```

## Features

- **Real-time Output Streaming**: Outputs cursor-agent results in real-time as they arrive (default mode)
- **Formatted Stream-JSON Output**: The output is parsed and formatted for better readability
- **Color-coded Output**: Different message types (system, user, thinking, assistant, tool_call) are displayed in different colors
- **Aggregated Output**: Messages of the same type are aggregated together instead of being displayed on separate lines
- **Extended Permissions Setup**: `--danger` flag for setting up cursor-agent permissions

## Usage

### Quick Start (推荐)

```bash
# 默认流式输出模式
cursor-cli "Analyze this project"

# 等效于:
cursor-cli --output-format stream-json --stream-partial-output -p "Analyze this project"
```

### Text Mode

```bash
# 使用 --text 切换到文本输出模式
cursor-cli --text "Analyze this project"

# 等效于:
cursor-cli --output-format text -p "Analyze this project"
```

### Danger Mode (Extended Permissions)

Setup extended permissions for cursor-agent in `.cursor/cli-config.json`:

```bash
# 在用户 home 目录下创建 ~/.cursor/cli-config.json
cursor-cli --danger

# 在指定目录下创建 .cursor/cli-config.json
cursor-cli --danger /path/to/project
```

This will create/update the config file with these permissions:

```json
{
  "permissions": {
    "allow": [
      "Shell(*)",
      "Read(*)",
      "Write(**/agents/**/*)",
      "Write(**/.agents/**/*)"
    ],
    "deny": []
  }
}
```

### Runner-specific Options

```bash
# 默认流式模式（推荐）
cursor-cli "Your prompt here"

# 文本输出模式
cursor-cli --text "Your prompt here"

# 禁用颜色
cursor-cli --no-color "Your prompt"

# 禁用格式化输出（原始 JSON）
cursor-cli --no-format "Your prompt"

# Show runner help
cursor-cli --runner-help
```

### Programmatic Usage

```python
from cursor_cli import CursorCLIRunner, cursor_cli

# Simple function call
result = cursor_cli("Hello, what can you do?")
print(result)

# Streaming output
for line in cursor_cli("Explain Python", stream=True):
    print(line)

# JSON output
result = cursor_cli("Analyze this", json=True)
print(result)

# Using the runner class
runner = CursorCLIRunner(use_colors=True)
exit_code = runner.run(["-p", "your prompt", "--output-format", "stream-json", "--stream-partial-output"])
```

### Using the Formatter Directly

```python
from cursor_cli import StreamJsonFormatter
import sys

# Create formatter
formatter = StreamJsonFormatter(output=sys.stdout, use_colors=True)

# Process JSON lines
formatter.process_line('{"type":"system","subtype":"init","model":"Composer 1"}')
formatter.process_line('{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Hello"}]}}')

# Finalize when done
formatter.finalize()
```

## Output Format

When formatting is enabled, the output is displayed as:

```
[SYSTEM:init] Model: Composer 1 | CWD: /path/to/dir | Permission: default | Session: abc12345...

[USER] your prompt text here

[THINKING] (thinking content if any)

[ASSISTANT] Response from the assistant...

[TOOL_CALL:started] 🔧 Tool #1: $ command to execute

[TOOL_CALL:completed]    ✓ Success

[TOOL_CALL:started] 📝 Tool #2: Creating analysis.txt

[TOOL_CALL:completed]    ✓ Created 15 lines (1234 bytes)

[RESULT] 🎯 Completed in 2.5s | 📊 Stats: 2 tools, 350 chars generated
```

### Color Scheme

- **SYSTEM**: Cyan
- **USER**: Green
- **THINKING**: Dim gray
- **ASSISTANT**: Yellow
- **TOOL_CALL**: Magenta
- **RESULT**: Bold Green

## CLI Options

| Option            | Description                                     |
| ----------------- | ----------------------------------------------- |
| `"prompt"`        | Default streaming mode with formatted output    |
| `--text "prompt"` | Text output mode                                |
| `--danger [path]` | Setup extended permissions (default: ~/.cursor) |
| `--no-color`      | Disable colored output                          |
| `--no-format`     | Disable output formatting (raw JSON)            |
| `--runner-help`   | Show help message                               |

## API Reference

### `cursor_cli()` Function

```python
cursor_cli(
    prompt: str,
    model: str = "composer-1",
    stream: bool = False,
    json: bool = False,
    **extra_args
) -> Union[str, dict, Iterator[str]]
```

| 参数           | 类型 | 默认值         | 说明                       |
| -------------- | ---- | -------------- | -------------------------- |
| `prompt`       | str  | 必填           | 发送给 cursor-agent 的提示 |
| `model`        | str  | `"composer-1"` | 使用的模型                 |
| `stream`       | bool | `False`        | 是否使用流式输出           |
| `json`         | bool | `False`        | 是否返回 JSON 格式         |
| `**extra_args` | -    | -              | 额外的命令行参数           |

**返回值:**

- `stream=False, json=False`: 返回 `str` 文本输出
- `stream=False, json=True`: 返回 `dict` 解析后的 JSON
- `stream=True`: 返回 `Iterator[str]` 生成器，逐行输出 JSON

## Message Types

The formatter handles the following message types from cursor-agent's stream-json output:

| Type        | Description                                              |
| ----------- | -------------------------------------------------------- |
| `system`    | System initialization and configuration                  |
| `user`      | User input/prompt                                        |
| `thinking`  | AI thinking process (streaming deltas)                   |
| `assistant` | AI response                                              |
| `tool_call` | Tool invocations (shell commands, file operations, etc.) |
| `result`    | Task completion with duration and statistics             |

### Supported Tool Types

| Tool             | Icon | Description             |
| ---------------- | ---- | ----------------------- |
| `shellToolCall`  | 🔧   | Shell command execution |
| `writeToolCall`  | 📝   | File creation           |
| `readToolCall`   | 📖   | File reading            |
| `editToolCall`   | ✏️   | File editing            |
| `listToolCall`   | 📂   | Directory listing       |
| `searchToolCall` | 🔍   | Code search             |

## Development

### Release to PyPI

```bash
# Install build dependencies
pip install build twine

# Release to PyPI (will prompt for token)
python scripts/release.py

# Release to TestPyPI first
python scripts/release.py --test
```

## Requirements

- Python >= 3.8
- `cursor-agent` must be installed and available in PATH

## License

MIT
