Skip to main content

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

Coding agent sandbox

codicent agent exec defaults to --sandbox workspace-write, which confines filesystem tools to --cwd. read-only also forbids file edits. Both modes reject shell commands because setting a command's working directory does not isolate its filesystem access. To allow shell commands, explicitly pass --sandbox danger-full-access; processes can then access files outside the workspace. --approval-policy on-request asks before mutations; never skips those prompts. Search and instruction discovery exclude links that escape their workspace or repository.

The codicent's own harness config (ADR-040, GET /app/GetHarnessConfig) is read before every turn. clients.cli.sandbox and clients.cli.approvalPolicy are ceilings on the two flags: asking for something looser exits 2 before anything runs, stricter is always allowed. tools.deny is applied locally as well, and an instructions hook means the server supplies the repository instructions itself, so AGENTS.md is not sent. If the config cannot be read the turn does not run (exit 1).

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.

Connect to a hosted terminal

codicent connect lists live codicent terminal sessions for the authenticated project and lets you select one. You can also connect directly by session id; list-only mode works without an interactive terminal:

codicent connect --list
codicent connect
codicent connect SESSION_ID

The client forwards keyboard input, ANSI output, and terminal resizes. Press Ctrl+] to detach without stopping the hosted shell; Ctrl+C is sent to the remote process. The CLI restores local terminal settings when the connection ends.

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
  • websocket-client: WebSocket transport for terminal hosting and connections

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.

Metadata

Release files for codicent-cli 0.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for codicent-cli 0.11.0
File Size Uploaded Provenance Actions
codicent_cli-0.11.0.tar.gz 73.6 kB Without provenance Details for codicent_cli-0.11.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for codicent-cli 0.11.0
File Interpreter ABI Platform Actions
codicent_cli-0.11.0-py3-none-any.whl Python 3 none any Details for codicent_cli-0.11.0-py3-none-any.whl

Total release size: 148.8 kB

Release files / codicent_cli-0.11.0.tar.gz

Download URL codicent_cli-0.11.0.tar.gz
Size 73.6 kB
Tags Source
SHA-256 checksum
How to use checksums
a862757cf9159fa2a78d3e0d708422c579e29fbc3eae045c3a60f3343eea44e3
BLAKE2b-256 checksum
How to use checksums
2918a355d2a8b00a5decdabcba94c3d0fac0abe5ae03fa68352049af768d46b5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Release files / codicent_cli-0.11.0-py3-none-any.whl

Download URL codicent_cli-0.11.0-py3-none-any.whl
Size 75.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ce2131ae51e53f845ba2ef275748ef6755583a05e70a85275c5cad0771ab12be
BLAKE2b-256 checksum
How to use checksums
0ec8394f6cd9623d7a8c90a0427a31c56c25840251898fdd53c3e873ef1fc685
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Security for codicent-cli 0.11.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page