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
-
Clone the repository:
git clone https://github.com/izaxon/codicent-cli.git cd codicent-cli
-
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.
Basic Setup
-
Set the
CODICENT_TOKENenvironment 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_tokento your.gitignoreto 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 optionallabelshown 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
#datamessages — 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
- Starts the specified tool as a local subprocess with full stdin/stdout control.
- Opens a session tagged
#wrap #wrap_<id>in your codicent project. - Output from the tool is captured and posted to codicent tagged
#wrap #wrap_<id> #output. - 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 bridgetest_app.py- Comprehensive test suitesetup.py- Package configurationrequirements.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
-
"CODICENT_TOKEN environment variable is not set"
- Set the token:
export CODICENT_TOKEN="your_token" - Verify it's set:
echo $CODICENT_TOKEN
- Set the token:
-
"Network error: Unable to connect to Codicent API"
- Check your internet connection
- Verify the Codicent API is accessible
- Try again with
--verbosefor more details
-
"Failed to initialize Codicent API client"
- Verify your token is valid
- Check if the codicent-py package is properly installed
Getting Help
- Use
codicent --helpfor usage information - Use
codicent --verbosefor 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.9.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| codicent_cli-0.9.0.tar.gz | 67.8 kB | Without provenance | Details for codicent_cli-0.9.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| codicent_cli-0.9.0-py3-none-any.whl | Python 3 | none | any | Details for codicent_cli-0.9.0-py3-none-any.whl |
Total release size: 136.8 kB
Release files / codicent_cli-0.9.0.tar.gz
| Download URL | codicent_cli-0.9.0.tar.gz |
|---|---|
| Size | 67.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a2d6a40f031b08bb0b54b6fcd78b1d689d2755c245c2f0be6200cd598434cbfd
|
|
BLAKE2b-256 checksum How to use checksums |
f7f4a95ad9acab9c2f2414d07ef063db1f1da43cf623c5ccca6ea5702a048090
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.9
|
Release files / codicent_cli-0.9.0-py3-none-any.whl
| Download URL | codicent_cli-0.9.0-py3-none-any.whl |
|---|---|
| Size | 69.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
03ca51c1dbf89adb4146715c4a243fbfa311f26695a596dfa4d9b2b9156a6a7b
|
|
BLAKE2b-256 checksum How to use checksums |
72c029c67cb8e8a8ba5c67d7240c7255dd9797ed1db5b08b2962cfd7f62d1f7f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.9
|
Security for codicent-cli 0.9.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.