codicent-cli 0.8.2

Command-line interface for the Codicent API

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

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

Development Installation

Steps

1. Clone the repository:

   git clone https://github.com/izaxon/codicent-cli.git
   cd codicent-cli
   

2. Install in development mode:

   pip install -e .
   

Direct Installation from GitHub

You can also install directly from GitHub:

# 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:

   export CODICENT_TOKEN="YOUR_API_TOKEN"
   

   Or use the built-in device-flow authentication:

   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:

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:

codicent "What can you help me with?"
codicent "Explain Python decorators"

Interactive mode:

codicent -t
# or
codicent --interactive

Piped input:

echo "What is machine learning?" | codicent
codicent < questions.txt
cat code.py | codicent "Review this code"

Info messages (@ prefix):

codicent "@mention This is an info message"

With logging:

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.

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.

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)

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

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 for API details

License

This project is licensed under the MIT License.