Skip to main content

⚡ agenticli

Expose tools as lightweight CLI commands for LLM agents 🔧✨

English | 中文

Python License PyPI Version GitHub


✨ 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 , description appended 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)

Source distribution for agenticli 0.2.5
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)

Table of built distributions (wheels) for agenticli 0.2.5
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

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