agent-tool-shared-cli

The shared chassis for the agent-tool-<x>-cli family — agent-ready command-line tools that an LLM can drive with no prior knowledge of them.

pip install agent-tool-shared-cli

The tools built on it — each learns the same contract, so an agent that knows one knows them all:

This repo also holds the family's engineering docs — read these first if you are standing up a new tool:

• BLUEPRINT.md — the engineering standard the whole family is built to.
• BUILDING-THE-NEXT-CLI.md — the distilled playbook, and why similarity is the product.
• SIMILARITY_CHECKLIST.md — tick every box before a new CLI is "done", so it lands already looking like its siblings.

Keywords: agent CLI chassis, LLM tool contract, exit-code taxonomy, JSON output CLI, keyring credentials, Python CLI library, AI agent tooling, Claude.

What's in it

This package is deliberately small. It holds the agent contract and the pure utilities that implement it — the things that must be identical across every tool, because an agent learns the contract once and applies it everywhere.

from agentcli import AppSpec, Credentials, Emitter, OutputFormat, NotFoundError

SPEC = AppSpec(name="drone-cli", env_prefix="DRONECLI")

SPEC.config_dir()            # ~/.config/drone-cli  (or $DRONECLI_CONFIG_DIR)
SPEC.env("TOKEN")            # "DRONECLI_TOKEN"

Credentials(SPEC).get_token("default")     # env > keyring > 0600 file
Emitter(OutputFormat.json, fields=["id", "status"]).emit(rows)
raise NotFoundError("no such build")       # -> exit 5, JSON on stderr

The exit-code contract

Published API. You may leave a code unallocated, or repurpose one deliberately. You may never renumber one — agents branch on these, and they are documented in three places per tool (README, the in-binary guide, and the Claude skill).

What is deliberately NOT here

client.py, serialize.py, resolve.py and the domain commands stay in each tool. They look shareable and are not:

OpenProject stops paginating on an authoritative total — "never stop on a short page". Drone has no total, and a short page is the terminator. The rule that inverts between tool #1 and tool #2 is exactly the rule you must not hoist.

Auth schemes, retry matrices and error-body shapes are the same story. Pulling them in would make this a framework with a config object per tool, which is how shared-code projects die.

Share the contract, not the transport.

Contributing

You need nothing but Python:

pip install -e '.[test]'
pytest                       # 74 tests, no network, no services

Changes here affect every downstream CLI. Two rules:

1. Never renumber an exit code, and never change an output shape without treating it as a breaking change — downstream agents depend on both.
2. Don't add a module because two tools happen to share it today. Wait until a third does, and until you can state the rule it obeys. tests/test_contract.py is the tripwire: if a change makes you edit it, stop and think.

License

MIT — see LICENSE.