Metadata-Version: 2.4
Name: codicent-cli
Version: 0.8.2
Summary: Command-line interface for the Codicent API
Home-page: https://github.com/izaxon/codicent-cli
Author: Johan Isaksson
Author-email: johan@izaxon.com
Project-URL: Bug Reports, https://github.com/izaxon/codicent-cli/issues
Project-URL: Source, https://github.com/izaxon/codicent-cli
Keywords: codicent cli api chat ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich
Requires-Dist: codicent-py
Requires-Dist: prompt_toolkit
Requires-Dist: requests
Requires-Dist: pyyaml
Requires-Dist: packaging
Requires-Dist: pyte
Requires-Dist: websocket-client
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Codicent CLI

Codicent CLI is a command-line interface for interacting with the Codicent API. It provides both one-shot command execution and interactive chat sessions with comprehensive error handling and user-friendly features.

## Features

- **One-shot mode**: Execute single commands and get responses
- **Interactive mode**: Continuous chat sessions with conversation tracking
- **Message types**: Support for regular chat and @-prefixed info messages
- **Input flexibility**: Command arguments, stdin pipes, or interactive prompts
- **Rich output**: Markdown-formatted responses with beautiful terminal UI
- **Error handling**: Comprehensive error messages and graceful failure handling
- **Logging**: Configurable logging levels for debugging

## Installation

### Prerequisites

- Python 3.6 or higher
- `pip` (Python package installer)

### Quick Installation

```bash
# Install from PyPI
pip install codicent-py codicent-cli
```

### Development Installation

#### Steps

1. Clone the repository:
   ```bash
   git clone https://github.com/izaxon/codicent-cli.git
   cd codicent-cli
   ```

2. Install in development mode:
   ```bash
   pip install -e .
   ```

### Direct Installation from GitHub

You can also install directly from GitHub:

```bash
# Install the latest version
pip install git+https://github.com/izaxon/codicent-cli.git

# Install a specific version
pip install git+https://github.com/izaxon/codicent-cli.git@v0.4.8
```

## Usage

### Basic Setup

1. Set the `CODICENT_TOKEN` environment variable with your Codicent API token:
   ```bash
   export CODICENT_TOKEN="YOUR_API_TOKEN"
   ```

   Or use the built-in device-flow authentication:
   ```bash
   codicent auth          # stores token globally in ~/.codicent_token
   codicent auth --local  # stores token in .codicent_token in the current directory
   ```

### Per-folder Projects

You can have a different Codicent project per directory by storing a local token:

```bash
cd ~/work/projectA
codicent auth --local   # authenticates and saves token to ~/work/projectA/.codicent_token

cd ~/work/projectB
codicent auth --local   # authenticates and saves token to ~/work/projectB/.codicent_token
```

The CLI always checks the current directory first, then falls back to the global `~/.codicent_token`, and finally to the `CODICENT_TOKEN` environment variable.

> **Tip**: Add `.codicent_token` to your `.gitignore` to avoid accidentally committing tokens.

### Command Options

```
codicent [OPTIONS] [QUESTION]

OPTIONS:
  -t, --interactive    Start interactive chat mode
  -h, --help          Show help message
  -v, --version       Show version information
  --verbose           Enable verbose logging
  --quiet             Suppress non-essential output
```

### Examples

**One-shot questions:**
```bash
codicent "What can you help me with?"
codicent "Explain Python decorators"
```

**Interactive mode:**
```bash
codicent -t
# or
codicent --interactive
```

**Piped input:**
```bash
echo "What is machine learning?" | codicent
codicent < questions.txt
cat code.py | codicent "Review this code"
```

**Info messages (@ prefix):**
```bash
codicent "@mention This is an info message"
```

**With logging:**
```bash
codicent --verbose "Debug this issue"
codicent --quiet "Silent operation"
```

## Interactive Mode

In interactive mode, you can have ongoing conversations with enhanced visual clarity:

```
$ codicent -t
🤖 Codicent CLI Interactive Mode
Type your questions or use Ctrl+C to exit.
Prefix with @ for info messages.
──────────────────────────────────────────────────
¤ What is Python?

Python is a high-level, interpreted programming language known for its 
simplicity and readability. It was created by Guido van Rossum and first 
released in 1991.

Key features:
• Easy to learn and use
• Extensive standard library
• Cross-platform compatibility
• Strong community support
──────────────────────────────────────────────────
¤ Can you give me an example?

Here's a simple Python example:

# Hello World in Python
print("Hello, World!")

# Working with variables
name = "Alice"
age = 25
print(f"My name is {name} and I am {age} years old.")

Python's syntax is clean and intuitive!
──────────────────────────────────────────────────
¤ @mention Save this conversation
✅ Message posted successfully.
──────────────────────────────────────────────────
¤ ^C
👋 Goodbye!
```

**Visual Features:**
- **Colored messages**: User input appears in cyan, bot responses in green
- **Clean prompting**: Original `¤` prompt character maintained
- **Visual separators**: Clear lines between conversations
- **Rich formatting**: Markdown responses with syntax highlighting
- **Status indicators**: Animated thinking indicators and success messages
- **Emojis**: Friendly visual cues throughout the interface

## Error Handling

The CLI provides helpful error messages for common issues:

- **Missing token**: Clear instructions on setting up `CODICENT_TOKEN`
- **Network errors**: Graceful handling of connection issues
- **API errors**: Detailed error messages from the Codicent API
- **Input validation**: Prevents empty or overly long inputs
- **Keyboard interrupts**: Clean exit handling

## Project Init

Use `codicent init` to instantly set up a new project from a template. Each template posts a ready-to-use set of AI instructions, configuration, automation rules, and sample data.

```bash
codicent init --list                              # list templates
codicent init                                     # use default template
codicent init --template koi-studio              # CRM pipeline
codicent init --template document-processing     # document intake
codicent init --template koi-studio --dry-run    # preview without posting
codicent init --force                            # re-init even if already set up
```

### Available templates

| Template | Description |
|---|---|
| `default` | General-purpose: task workflow, auto-summarize notes via `#transform` |
| `koi-studio` | CRM: automatic lead extraction from raw text, follow-up email drafting |
| `document-processing` | Document intake: extract text, structure key fields with AI, review workflow |

### How it works

Templates are JSON files in `templates/`. Each defines:
- **`variables`** — prompted at init time (e.g. company name). Values with defaults are applied silently; values without defaults require manual entry.
- **`messages`** — posted in order. Each has an optional `label` shown in progress output.

Key message types posted by templates:
- `#instructions` — sets the AI assistant's persona and focus
- `#appconfig #data` — configures AI model, temperature, and token limit
- `#process #data` — defines pipeline stages (shown as kanban columns in the UI)
- `#transform #data` — automation rule: when a message with tag X arrives, run AI and produce a message with tag Y
- sample `#data` messages — so lists aren't empty on first login

### `--dry-run` mode

Prints every message that *would* be posted, with its label and a content preview, without any API calls or auth required. Useful for reviewing a template before committing.

## Wrap — AI CLI Remote Chat Bridge

Use `codicent wrap` to bridge a local AI CLI tool (`claude`, `codex`, `opencode`, etc.) to your codicent project chat. Remote users and the Codicent AI can interact with the locally running tool in real time through the existing codicent web UI.

```bash
codicent wrap claude                              # wrap Claude Code
codicent wrap opencode                            # wrap OpenCode
codicent wrap --label "Refactor sprint" codex     # named session
codicent wrap --poll-interval 5 claude            # slower polling
codicent wrap --binary /opt/ai/claude claude      # explicit binary path
```

### How it works

1. Starts the specified tool as a local subprocess with full stdin/stdout control.
2. Opens a **session** tagged `#wrap #wrap_<id>` in your codicent project.
3. **Output** from the tool is captured and posted to codicent tagged `#wrap #wrap_<id> #output`.
4. **Input** is received by polling for messages tagged `#wrap #wrap_<id> #input` — any message posted remotely with those tags is forwarded to the tool's stdin.

The session ID is printed on startup. To send text to the running tool from the codicent web UI, post a message with `#wrap_<id> #input` in the content.

### Startup output

```
🔗 Wrap session starting…
   Session ID: wrap_a3f7c1b2
   Project:    myproject
   Tool:       claude  (/usr/local/bin/claude)
   Remote tag: #wrap_a3f7c1b2
   Post messages tagged #wrap_a3f7c1b2 #input to send text to the tool.
   Press Ctrl+C to stop the session.
```

### Configuration (`~/.codicent/wrap-config.yaml`)

```yaml
poll_interval: 2          # seconds between input polls
output_batch_ms: 500      # ms to batch output before posting

tools:
  claude:
    binary: claude        # binary name or full path
  codex:
    binary: codex
  opencode:
    binary: opencode

auto_responses:
  - pattern: "Do you want to continue"
    reply: "y"
  - pattern: "\\(y/n\\)"
    reply: "y"
```

Auto-response rules are matched against subprocess output using regex. When matched, the configured reply is written to stdin automatically (and posted to codicent for visibility).

If no config file exists, defaults are used: tools are resolved by name on `$PATH`, poll interval is 2 seconds.

## Development

### Running Tests

```bash
python -m pytest test_app.py -v
```

### Project Structure

- `app.py` - Main application logic (single-file architecture)
- `wrap.py` - Wrap command: AI CLI remote chat bridge
- `test_app.py` - Comprehensive test suite
- `setup.py` - Package configuration
- `requirements.txt` - Dependencies (now uses PyPI packages)

### Dependencies

- **codicent-py**: Core API client for Codicent services (now available on PyPI)
- **rich**: Terminal formatting, markdown rendering, and animations
- **pyyaml**: YAML config file parsing for the wrap command

## Troubleshooting

### Common Issues

1. **"CODICENT_TOKEN environment variable is not set"**
   - Set the token: `export CODICENT_TOKEN="your_token"`
   - Verify it's set: `echo $CODICENT_TOKEN`

2. **"Network error: Unable to connect to Codicent API"**
   - Check your internet connection
   - Verify the Codicent API is accessible
   - Try again with `--verbose` for more details

3. **"Failed to initialize Codicent API client"**
   - Verify your token is valid
   - Check if the codicent-py package is properly installed

### Getting Help

- Use `codicent --help` for usage information
- Use `codicent --verbose` for detailed logging
- Check the [Codicent documentation](https://github.com/izaxon/codicent-py) for API details

## License

This project is licensed under the MIT License.
