✨ What is this?
agenticli converts functions, classes, and schema-based tools into a stable CLI semantic layer. Instead of flooding prompts with large schemas, LLMs just output a single command string.
💡 Philosophy: bash is everything. The command string is the most stable, restrained, and observable intermediate representation between LLMs and tool systems.
🎯 When to use agenticli?
| Scenario | agenticli helps? |
|---|---|
| You have many tools/functions and need a unified interface for LLMs | ✅ |
| You don't want massive schemas injected into prompts | ✅ |
You want models to see minimal hints, expanding via --help |
✅ |
| You want validation, help, errors, and lifecycle in one place | ✅ |
🚀 Quick Start
pip install agenticli
from typing import Annotated
from agenticli import CommandRegistry, Option, command, command_group
@command_group(name="calc", description="Calculator commands")
class Calc:
@command(name="add", description="Add numbers")
def add(self,
values: Annotated[list[float], Option(positional=True, value_name="n")]
) -> dict:
return {"result": sum(values)}
registry = CommandRegistry()
registry.register(Calc)
# LLM sees this minimal command context:
print(registry.render_llm_context())
# -> You can use the following CLI commands:
# calc: Calculator commands
result = registry.execute("calc add 10 20 30")
print(result.value if result.ok else result.error.render())
# -> {"result": 60.0}
🏗️ Core Architecture
┌─────────────────────────────────────────────────────────────┐
│ LLM Output │
│ "calc add 10 20 30" │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CommandRegistry │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│ │ Parse │─▶│ Validate │─▶│ Execute │─▶│ Result │ │
│ └──────────┘ └──────────┘ └──────────┘ └────────────┘ │
│ │
│ • Command hit/matching • Lifecycle callbacks │
│ • Help generation • Error with suggestions │
│ • Argument injection • Chain execution (&&, ||, ;) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Your Functions / Tools │
└─────────────────────────────────────────────────────────────┘
📋 Key Features
| Feature | Description |
|---|---|
| 🔌 Multiple Registrations | Decorators, class inheritance, dataclass, Pydantic, schema wrapping |
| ⚡ CLI Parsing | Positional args, quoted args, --option value, -o value, --opt=val, flags |
| 📖 Smart Help | Auto-generated usage, help text, LLM prompts |
| ✅ Validation | Type coercion, requires/excludes, enums |
| 💡 Suggestions | "Did you mean X?" for unknown commands/options/enums |
| 🔄 Lifecycle Hooks | before_execute, after_execute, on_error |
| 🏃 Internal Injection | Hide callbacks/state from CLI, inject at runtime |
| 🔗 Chain Execution | Quote-aware `cmd1 && cmd2 |
| ⏳ Async Execution | Native execute_async(..., chain=False) |
| 🔌 Tool Import | Convert LangChain / AutoGen / OpenAI-style tools into CommandSpec |
📝 Registration Patterns
1️⃣ Decorator (Most Common)
from typing import Annotated
from agenticli import command, Option
@command(name="ls", description="List directory")
def ls(
path: Annotated[str, Option(short='p', description="Directory path")],
verbose: Annotated[bool, Option(short='v')] = False,
) -> list[str]:
import os
return os.listdir(path)
2️⃣ Command Group
from agenticli import command_group, command
@command_group(name="db", description="Database operations")
class Database:
@command(description="Create database")
def create(self, name: str) -> None: ...
@command(description="Drop database")
def drop(self, name: str) -> None: ...
3️⃣ Wrap Existing Tools
from agenticli import wrap_tool
class MyTool:
name = "my_tool"
description = "Does something"
parameters = {"type": "object", "properties": {"x": {"type": "int"}}}
async def execute(self, **kwargs): return kwargs
registry.register_spec(wrap_tool(MyTool()))
4️⃣ Class Inheritance
from agenticli import CliCommand, CommandRegistry
class AddCommand(CliCommand):
name = "add"
description = "Add numbers"
args_model = AddArgs
async def run(self, **kwargs) -> dict:
return {"result": sum(kwargs["values"])}
registry.register(AddCommand())
🤖 LLM Integration
Minimal Tool Schema
Expose only one exec tool to the LLM:
from agenticli import ExecTool
def run_command(command: str, **kwargs):
result = registry.execute(command)
return result.value if result.ok else result.error.render()
exec_tool = ExecTool(callback=run_command)
# Tool schema: {name: "exec", params: {command: string, timeout?: int}}
Lifecycle Callbacks
from agenticli import ExecutionCallbacks
def on_error(ctx):
print(f"Error: {ctx.error.code} - {ctx.error.message}")
registry = CommandRegistry(
callbacks=ExecutionCallbacks(on_error=on_error)
)
Internal Parameter Injection
from typing import Annotated
from agenticli import Callback, State, command
@command(name="process")
def process(
data: list[str],
cache: Annotated[object, State(factory=lambda ctx: load_cache())] = None,
):
# cache is injected automatically, hidden from CLI
return cached_transform(data, cache)
🔌 Import External Tools
You can wrap existing framework tools into agenticli commands through
functions in agenticli.adapters:
from agenticli import CommandRegistry
from agenticli.adapters import (
wrap_autogen_tool,
wrap_langchain_tool,
wrap_openai_tool_schema,
)
registry = CommandRegistry()
registry.register_spec(wrap_langchain_tool(my_langchain_tool))
registry.register_spec(wrap_autogen_tool(my_autogen_tool))
registry.register_spec(
wrap_openai_tool_schema(
name="search_docs",
description="Search docs",
parameters={
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
handler=lambda query: {"query": query},
)
)
⚡ Async API
agenticli now supports native async execution:
result = await registry.execute_async("calc add 1 2 3")
items = await registry.execute_async("cmd1 ; cmd2", chain=True)
🧾 Command Syntax
Command parsing uses shell-style quoting for arguments:
weather "New York" --unit fahrenheit
say 'single quoted text'
say "arg with \"nested\" quotes"
Backslash-newline continuations are normalized before parsing:
weather "New York" \
--unit fahrenheit
Command chains support ;, &&, and ||. Operators inside quotes stay part
of the argument instead of splitting the chain:
say "hello ; world" ; say done
say "hello && world" && say ok
Invalid input returns structured errors:
result = registry.execute('weather "Beijing')
assert result.ok is False
assert result.error.code == "parse_error"
registry.execute("missing && weather Beijing", chain=True)
# ["Error: Unknown command"]
📖 Auto-Generated Help
<name> --help and registry.help(name) render help from each command's
ValidationAdapter.help_text(). Given:
@command_group(name="files", description="File and text operations")
class Files:
@command(name="ls", description="List directory contents")
def ls(
self,
path: Annotated[str, Option(short="p", description="Directory path", value_name="PATH", example="/tmp")],
verbose: Annotated[bool, Option(short="v", description="Also list hidden entries")] = False,
ext: Annotated[str, Option(short="e", description="Filter by extension", value_name="EXT", example=".log")] = "",
) -> list[str]: ...
files ls --help renders:
files ls - List directory contents
Usage:
ls --path <PATH> [--verbose] [--ext <EXT>]
Args:
-p,--path PATH required example:/tmp, Directory path
-v,--verbose flag default:false, Also list hidden entries
-e,--ext EXT default: example:.log, Filter by extension
Group help lists subcommands instead of arguments. The LLM-facing prompt
from registry.render_llm_context() is intentionally minimal and does
not embed the full help — it tells the model to use
<command> --help when it needs more.
0.2.5: the auto-generated help is now a flat, single-line-per-arg layout —
Header/Usage/Args. Modifiers on each arg are space-separated (flag,required,default:X,enum:[…],example:X) with, descriptionappended at the end.
📦 Stable API
# Core
CommandRegistry
CommandRegistry.register(target)
CommandRegistry.register_spec(spec)
CommandRegistry.unregister(name)
CommandRegistry.get(name)
CommandRegistry.has(name)
CommandRegistry.parse(command_str, chain=False)
CommandRegistry.execute(command_str, chain=False)
CommandRegistry.execute_async(command_str, chain=False)
CommandRegistry.discover(directory, *, context_provider=None, recursive=True, package=None, on_error="ignore")
CommandRegistry.match(text, chain=False, mode="command")
CommandRegistry.help(command=None)
CommandRegistry.render_llm_context(detailed=False)
CommandRegistry.commands
# Decorators
command(_func=None, *, name=None, description="", aliases=None, hidden=False, deprecated=None, include_in_prompt=None)
command_group(name="", description="", *, include_in_prompt=True, register_as_command=None)
# Helpers
CliCommand
wrap_tool(tool)
command_from_model(name, model, handler)
command_from_method(name, target, method_name)
wrap_langchain_tool(tool)
wrap_autogen_tool(tool)
wrap_openai_tool_schema(name, parameters, handler, ...)
Option
Injected / Callback / State
ExecutionCallbacks
ExecTool
Upgrading from 0.1.x? See docs/migration_0.2.md.
💡 Examples
See example/provider_integration.py for a complete calc system with OpenAI/Anthropic integration:
pip install "agenticli[examples]"
python -m example.provider_integration --provider openai
python -m example.provider_integration --provider anthropic
For a local Linux-like command demo (pwd, cd, ls, cat, head, grep, wc):
python -m example.linux_like_shell
Usage pattern demos:
python -m example.decorator
python -m example.command_group
python -m example.cli_command
python -m example.command_from_model
python -m example.command_from_method
python -m example.wrap_tool
python -m example.external_adapters
python -m example.discover
python -m example.context_group_instance
python -m example.context_state_factory
python -m example.context_init
🔎 Auto-Discovery
CommandRegistry.discover() walks a directory and registers every class
that opts in via @command_group or by subclassing CliCommand. An
optional context_provider callback binds request-scoped context to
each discovered class — useful when the same registry powers many
tenants:
from agenticli import CommandRegistry
def provide_context(cls):
if cls is UserService:
return cls(user_id="alice", tenant_id="acme")
return cls()
registry = CommandRegistry()
result = registry.discover(
"example/discover_cmds",
context_provider=provide_context,
package="example.discover_cmds",
)
print(result.registered) # newly added command names
print(result.errors) # per-file failures (when on_error="ignore")
See example/discover.py for a runnable demo.
📚 Documentation
| Language | Link |
|---|---|
| 🇺🇸 English README | README.md |
| 🇨🇳 中文 README | README_zh.md |
| 🇺🇸 English | docs/index_en.md |
| 🇨🇳 中文 | docs/index_zh.md |
| Migration | docs/migration_0.2.md |
📄 License
MIT
Metadata
Release files for agenticli 0.2.5
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 |
|---|---|---|---|---|
| agenticli-0.2.5.tar.gz | 179.6 kB | With provenance | Details for agenticli-0.2.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agenticli-0.2.5-py3-none-any.whl | Python 3 | none | any | Details for agenticli-0.2.5-py3-none-any.whl |
Total release size: 227.0 kB
Release files / agenticli-0.2.5.tar.gz
| Download URL | agenticli-0.2.5.tar.gz |
|---|---|
| Size | 179.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
028e9b711306d42ea8e5920b56c06dea2affdf24efff3c802ba50bea6cde3a32
|
|
BLAKE2b-256 checksum How to use checksums |
efdb534ffa3e40df30a8697569071c405ecf27ac952416b5a77532c16d4f9162
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 5, 2026.
Transparency logRelease files / agenticli-0.2.5-py3-none-any.whl
| Download URL | agenticli-0.2.5-py3-none-any.whl |
|---|---|
| Size | 47.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c1a432ef814af486b27251e2bd293f655a0f4fd36074773f18fbd8865e940a76
|
|
BLAKE2b-256 checksum How to use checksums |
855ebae813676ef74abbd4b5a0cc25c3dad119b29363c03014746a56f65aaf1c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 5, 2026.
Transparency logSecurity for agenticli 0.2.5
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agenticli-0.2.5.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 5, 2026.
Transparency logA 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.