humancli 0.1.0__tar.gz

humancli-0.1.0/.agents/AGENTS.md

@@ -0,0 +1,4 @@
+after you finish work, commit with a conventional message. only commit the files you edited.
+always run tests before code commits.
+when using gh to edit or create PR descriptions, prefer `--body-file` to preserve newlines.
+always include a "Manual testing" checklist section in PRs.

humancli-0.1.0/.agents/skills/release/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: release
+description: Prepare and ship an agentcli release. Use when asked to cut a release, bump release versions, tag v<major.minor.patch>, or trigger the GitHub release workflow.
+---
+
+# Release
+
+## Overview
+
+Prepare a tagged release that matches the GitHub Actions release workflow. The workflow requires the tag version to match both `pyproject.toml` and `src/agentcli/__init__.py`.
+
+## Workflow
+
+### 1) Choose version + date
+
+Pick the release version (major.minor.patch) and the release date (YYYY-MM-DD).
+If the current version has a `.dev` suffix, assume the target release version is the same version without the suffix, as long as that tag does not already exist.
+
+### 2) Bump versions
+
+Update version strings to match the release tag:
+
+- `pyproject.toml`: `project.version = "<major.minor.patch>"`
+- `src/agentcli/__init__.py`: `__version__ = "<major.minor.patch>"`
+- `uv.lock`: refresh so the root package version matches (run `uv lock` or `uv sync`).
+
+### 3) Run checks
+
+Run tests before committing:
+
+- `uv run python -m unittest tests/test_agentcli.py`
+
+### 4) Commit + tag
+
+Commit the release using conventional commits:
+
+- Commit message: `chore(release): v<major.minor.patch>`
+- Tag: `git tag v<major.minor.patch>`
+
+Push the tag to trigger `.github/workflows/release.yml` (build, PyPI publish, GitHub release).
+
+### 5) Optional post-release bump
+
+If you keep a dev version between releases, bump the minor version (reset patch to 0) and commit (`chore: bump version to ...`).
+
+## Notes
+
+- The release workflow checks that the tag matches `pyproject.toml` and `src/agentcli/__init__.py`.

humancli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - "master"
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: ${{ matrix.task }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - task: format
+            do_sync: true
+            command: uv run --no-sync ruff format --check --diff src tests
+            sync_args: --no-install-project --group dev
+          - task: ruff
+            do_sync: true
+            command: uv run --no-sync ruff check src tests --output-format=github
+            sync_args: --no-install-project --group dev
+          - task: pytest
+            do_sync: true
+            command: uv run --no-sync python -m unittest discover tests -v
+            sync_args: ""
+          - task: build
+            do_sync: false
+            command: uv build
+            sync_args: ""
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Install dependencies
+        if: matrix.do_sync
+        run: uv sync --frozen ${{ matrix.sync_args }}
+
+      - name: Run check
+        run: ${{ matrix.command }}

humancli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,112 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Check tag matches project version
+        run: |
+          uv run --no-project python - <<'PY'
+          import os
+          import re
+          import tomllib
+          from pathlib import Path
+
+          tag = os.environ.get('GITHUB_REF_NAME', '')
+          tag_version = tag[1:] if tag.startswith('v') else tag
+
+          pyproject = tomllib.loads(Path('pyproject.toml').read_text(encoding='utf-8'))
+          project_version = pyproject['project']['version']
+
+          init_version = None
+          init_path = Path('src') / 'agentcli' / '__init__.py'
+          if init_path.is_file():
+            m = re.search(r'__version__\s*=\s*"([^"]+)"', init_path.read_text(encoding='utf-8'))
+            if m:
+              init_version = m.group(1)
+
+          if project_version != tag_version:
+            raise SystemExit(f"Tag {tag!r} does not match pyproject version {project_version!r}")
+          if init_version and init_version != project_version:
+            raise SystemExit(
+              f"src/agentcli/__init__.py __version__ {init_version!r} does not match pyproject version {project_version!r}"
+            )
+
+          print(f"OK: tag {tag!r} matches version {project_version!r}")
+          PY
+
+      - name: Run tests
+        run: uv run python -m unittest discover tests -v
+
+      - name: Build (wheel + sdist)
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI (trusted publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/humancli/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true
+
+  github-release:
+    name: Create GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub release and upload artifacts
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            dist/*

humancli-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Reference materials (embedded repos)
+reference/
+
+# Internal design notes
+PLAN.md

humancli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

humancli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaser Martinez Palenzuela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

humancli-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: humancli
+Version: 0.1.0
+Summary: Python CLIs for agents and humans
+Project-URL: Repository, https://github.com/elyase/agentcli
+Project-URL: Issues, https://github.com/elyase/agentcli/issues
+Author-email: Yaser Martinez Palenzuela <yaser.martinez@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,cli,command-line,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: docstring-parser>=0.16
+Provides-Extra: all
+Requires-Dist: mcp>=1.0; extra == 'all'
+Requires-Dist: pydantic>=2.0; extra == 'all'
+Requires-Dist: pyyaml>=6.0; extra == 'all'
+Requires-Dist: rich>=13.0; extra == 'all'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == 'pydantic'
+Provides-Extra: rich
+Requires-Dist: rich>=13.0; extra == 'rich'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# agentcli
+
+Python CLIs for agents and humans.
+
+agentcli builds command-line interfaces that produce structured, parseable output for AI agents while remaining human-friendly. Type hints are the schema — a function signature IS the CLI specification.
+
+## Install
+
+```sh
+pip install humancli
+```
+
+The package installs as `humancli` on PyPI but you import it as `agentcli`:
+
+```python
+from agentcli import App
+```
+
+## Quick start
+
+### Single function
+
+```python
+from agentcli import run
+
+def greet(name: str):
+    """Greet someone."""
+    return {"message": f"hello {name}"}
+
+run(greet)
+```
+
+```sh
+$ greet world
+message: hello world
+
+$ greet world --json
+{"ok": true, "data": {"message": "hello world"}}
+
+$ greet --llms
+# greet
+| Command | Description |
+|---------|-------------|
+| `greet <name>` | Greet someone |
+```
+
+### Multi-command app
+
+```python
+from agentcli import App
+
+app = App("my-cli", version="1.0.0")
+
+@app.command
+def status():
+    """Show status."""
+    return {"clean": True, "branch": "main"}
+
+@app.command
+def install(package: str, *, save_dev: bool = False):
+    """Install a package."""
+    return {"added": 1, "packages": 451}
+
+app()
+```
+
+Parameters before `*` are positional arguments. Parameters after `*` are named options/flags. This is just Python's own syntax.
+
+### Parameter metadata
+
+```python
+from typing import Annotated, Literal
+from agentcli import App, Param
+
+app = App("deploy-cli")
+
+@app.command
+def deploy(
+    env: Annotated[Literal["staging", "prod"], Param(help="Target environment")],
+    *,
+    token: Annotated[str, Param(env="DEPLOY_TOKEN", secret=True)] = "",
+):
+    """Deploy to an environment."""
+    return {"url": f"https://{env}.example.com"}
+
+app()
+```
+
+### Sub-apps
+
+```python
+app = App("gh")
+pr = App("pr")
+
+@pr.command
+def list_(*, state: Literal["open", "closed"] = "open"):
+    """List pull requests."""
+    return {"prs": [], "state": state}
+
+app.mount(pr)
+app()
+
+# $ gh pr list --state closed
+```
+
+### Default commands
+
+```python
+app = App("fetch")
+
+@app.default
+def fetch_cases(*, limit: int = 20):
+    """Fetch cases."""
+    return {"fetched": limit}
+
+# Runs when no sub-command is given:
+# $ fetch --limit 5
+```
+
+## Agent discovery
+
+Every agentcli app gets built-in flags for agent consumption:
+
+- `--llms` — markdown command index
+- `--llms-full` — full JSON schema of all commands
+- `--json` / `--yaml` / `--jsonl` — structured output formats
+- `--mcp` — start as an MCP server (requires `agentcli[mcp]`)
+
+## Optional extras
+
+```sh
+pip install humancli[rich]      # rich terminal formatting
+pip install humancli[pydantic]  # pydantic model support
+pip install humancli[yaml]      # yaml output format
+pip install humancli[mcp]       # MCP server mode
+pip install humancli[all]       # everything
+```
+
+## License
+
+MIT

humancli-0.1.0/README.md

@@ -0,0 +1,141 @@
+# agentcli
+
+Python CLIs for agents and humans.
+
+agentcli builds command-line interfaces that produce structured, parseable output for AI agents while remaining human-friendly. Type hints are the schema — a function signature IS the CLI specification.
+
+## Install
+
+```sh
+pip install humancli
+```
+
+The package installs as `humancli` on PyPI but you import it as `agentcli`:
+
+```python
+from agentcli import App
+```
+
+## Quick start
+
+### Single function
+
+```python
+from agentcli import run
+
+def greet(name: str):
+    """Greet someone."""
+    return {"message": f"hello {name}"}
+
+run(greet)
+```
+
+```sh
+$ greet world
+message: hello world
+
+$ greet world --json
+{"ok": true, "data": {"message": "hello world"}}
+
+$ greet --llms
+# greet
+| Command | Description |
+|---------|-------------|
+| `greet <name>` | Greet someone |
+```
+
+### Multi-command app
+
+```python
+from agentcli import App
+
+app = App("my-cli", version="1.0.0")
+
+@app.command
+def status():
+    """Show status."""
+    return {"clean": True, "branch": "main"}
+
+@app.command
+def install(package: str, *, save_dev: bool = False):
+    """Install a package."""
+    return {"added": 1, "packages": 451}
+
+app()
+```
+
+Parameters before `*` are positional arguments. Parameters after `*` are named options/flags. This is just Python's own syntax.
+
+### Parameter metadata
+
+```python
+from typing import Annotated, Literal
+from agentcli import App, Param
+
+app = App("deploy-cli")
+
+@app.command
+def deploy(
+    env: Annotated[Literal["staging", "prod"], Param(help="Target environment")],
+    *,
+    token: Annotated[str, Param(env="DEPLOY_TOKEN", secret=True)] = "",
+):
+    """Deploy to an environment."""
+    return {"url": f"https://{env}.example.com"}
+
+app()
+```
+
+### Sub-apps
+
+```python
+app = App("gh")
+pr = App("pr")
+
+@pr.command
+def list_(*, state: Literal["open", "closed"] = "open"):
+    """List pull requests."""
+    return {"prs": [], "state": state}
+
+app.mount(pr)
+app()
+
+# $ gh pr list --state closed
+```
+
+### Default commands
+
+```python
+app = App("fetch")
+
+@app.default
+def fetch_cases(*, limit: int = 20):
+    """Fetch cases."""
+    return {"fetched": limit}
+
+# Runs when no sub-command is given:
+# $ fetch --limit 5
+```
+
+## Agent discovery
+
+Every agentcli app gets built-in flags for agent consumption:
+
+- `--llms` — markdown command index
+- `--llms-full` — full JSON schema of all commands
+- `--json` / `--yaml` / `--jsonl` — structured output formats
+- `--mcp` — start as an MCP server (requires `agentcli[mcp]`)
+
+## Optional extras
+
+```sh
+pip install humancli[rich]      # rich terminal formatting
+pip install humancli[pydantic]  # pydantic model support
+pip install humancli[yaml]      # yaml output format
+pip install humancli[mcp]       # MCP server mode
+pip install humancli[all]       # everything
+```
+
+## License
+
+MIT

humancli-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "humancli"
+version = "0.1.0"
+description = "Python CLIs for agents and humans"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Yaser Martinez Palenzuela", email = "yaser.martinez@gmail.com" }
+]
+requires-python = ">=3.11"
+keywords = ["cli", "agent", "llm", "ai", "command-line"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "docstring-parser>=0.16",
+]
+
+[project.optional-dependencies]
+rich = ["rich>=13.0"]
+pydantic = ["pydantic>=2.0"]
+yaml = ["pyyaml>=6.0"]
+mcp = ["mcp>=1.0"]
+all = ["humancli[rich,pydantic,yaml,mcp]"]
+
+[dependency-groups]
+dev = ["ruff>=0.11"]
+
+[project.urls]
+Repository = "https://github.com/elyase/agentcli"
+Issues = "https://github.com/elyase/agentcli/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentcli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

humancli-0.1.0/src/agentcli/__init__.py

@@ -0,0 +1,20 @@
+"""agentcli: Python CLIs for agents and humans."""
+
+from ._app import App, run
+from ._context import Context
+from ._errors import AgentCliError, ConfigError, ParseError, ValidationError
+from ._types import Param, Result
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentCliError",
+    "App",
+    "ConfigError",
+    "Context",
+    "Param",
+    "ParseError",
+    "Result",
+    "ValidationError",
+    "run",
+]