a2acli

README

A2A CLI

A standalone, A2A Specification v1.0 compliant command-line client for discovering, messaging, and managing agents. Built on the a2a-go SDK with an interactive streaming TUI and a scriptable JSON mode.

What is A2A?

A2A (Agent-to-Agent) is an open protocol for talking to AI agents over a network — discover what an agent can do, send it a message, and stream back results and artifacts, regardless of how the agent is built. Every agent publishes an AgentCard (its skills, security requirements, and transports); you send a message that creates a task; the task moves through states (working → completed) and may produce artifacts (text, data, files).

a2acli is the command-line client for that protocol. To learn the protocol itself, see the canonical site: a2a-protocol.org.

Installation

macOS and Linux — Homebrew

brew tap ghchinoy/tap
brew trust ghchinoy/tap
brew install a2acli

Linux — Install Script

curl -sL https://raw.githubusercontent.com/ghchinoy/a2acli/main/scripts/install.sh | bash

Linux — apt (Debian / Ubuntu)

Download the .deb from the latest release:

sudo dpkg -i a2acli_*.deb

Linux — rpm (Fedora / RHEL)

Download the .rpm from the latest release:

sudo rpm -i a2acli_*.rpm

Windows — winget

winget install ghchinoy.a2acli

Any platform — Go Install

go install github.com/ghchinoy/a2acli/cmd/a2acli@latest

Ensure your Go binary directory is exported in your shell profile (~/.bashrc, ~/.zshrc):

export PATH="$PATH:$(go env GOPATH)/bin"

To use a2a as a convenient shorthand for a2acli:

alias a2a="a2acli"

From Source

git clone https://github.com/ghchinoy/a2acli.git
cd a2acli
make build   # binary is written to bin/a2acli

Verify your install

a2acli version

You should see version, commit, and build-date information. If the command isn't found, ensure your install location (e.g. $(go env GOPATH)/bin for go install, or ./bin when building from source) is on your PATH.

5-Minute Tutorial

You don't need a remote agent to get started — a2acli can run a local mock agent for you. This golden path runs entirely on your machine, no auth required.

1. Start a local echo agent (in one terminal, or background it with &):

a2acli serve --echo --port 9001

2. Discover what it can do — fetch its AgentCard, skills, and security schemes:

a2acli discover --service-url http://localhost:9001

3. Send it a message and stream the response in real time:

a2acli send "Hello, agent!" --service-url http://localhost:9001

That's the full loop: serve → discover → send. The echo agent simply returns your message, which is exactly what you want when learning the mechanics.

4. Get a single JSON result instead of the interactive UI — this is the form scripts and AI agents use:

a2acli send "Hello, agent!" --service-url http://localhost:9001 --output json --wait

Graduating to a real agent

Once the loop makes sense, point the same commands at a real agent. If it's protected by OAuth 2.1, log in once and every later command is authenticated automatically — no --token needed:

a2acli auth login --service-url https://agent.example.com   # browser opens once
a2acli send "hello" --service-url https://agent.example.com --wait   # auto-authenticated

Tired of retyping URLs? Save a named environment and use --env:

a2acli config env add prod --service-url https://agent.example.com
a2acli send "hello" --env prod --wait

See the Reference Manual for full config details.

Command Overview

Commands are organized into four A2A-aligned groups. The table below is a map; the Reference Manual has the full flag lists, examples, and output schemas for each.

Command	Group	What it does
discover	Discovery	Fetch an agent's AgentCard, skills, and security schemes
send	Messaging	Send a message to initiate or continue a task
subscribe	Messaging	Subscribe to a running task's event stream
get	Messaging	Retrieve state and artifacts of a task by ID
list tasks	Messaging	List historical tasks (with --status/--context filters)
cancel	Messaging	Cancel an active task
push-config	Messaging	Manage push-notification callbacks for a task
download	Messaging	Download artifacts from a completed task
serve	Server	Run a local mock A2A agent for testing
auth	Config	OAuth 2.1 login/status/token/logout
conformance	Server	Run A2A conformance smoke checks against a live server
a2ui validate	Server	Validate A2UI v1.0 extension wire conformance
config	Config	Manage named environments

Output modes are controlled by --output: tui (default interactive), text (plain, for CI/pipes), and json (NDJSON for scripting). a2acli auto-degrades from tui to text when output isn't a terminal. See Output Modes.

For the complete grammar, every flag, global flags, shell completion, and automation guidance, see the Reference Manual.

Using a2acli from AI Coding Agents

a2acli is designed to be driven by AI coding agents (Claude Code, Cursor, GitHub Copilot CLI) as well as shell scripts. Two rules make it deterministic in non-interactive contexts:

1. Pass --output json (or -n) to disable the TUI and emit parseable NDJSON.
2. Pass --wait with send to block until the task completes.

This repository is a conformant Agent Plugins Specification v1.0.0 plugin package shipping agentskills.io compliant skills that teach coding agents how to use, build, and evaluate A2A services:

• a2acli — Teaches agents how to interact with A2A services from the command line using a2acli.
• a2a-expose — Guides developers and agents in adding a compliant A2A exposure layer to an existing API or service.
• a2a-conformance — Evaluates an A2A agent against normative spec rules, stable check IDs, and TCK orchestration.

See the Agent Skills Guide for full usage scenarios, prompt libraries, and authoring guidelines.

Development

make build      # Compile to bin/a2acli
make run        # Build and run
make lint       # Run golangci-lint
make test-e2e   # Run end-to-end conformance tests
make diagrams   # Re-render docs/diagrams/*.dot to docs/img/*.webp
make clean      # Remove bin/

For release instructions see docs/RELEASING.md.

Conformance (TCK)

a2acli is tested against the official A2A Technology Compatibility Kit for both v0.3.0 and v1.0.0. See the Conformance Report for current status.

Running the tests requires the a2a-go SDK source locally, as the suite spins up the TCK SUT server dynamically:

# Default path: ../../github/a2a-go
make test-e2e

# Custom path
make test-e2e A2A_GO_SRC=/path/to/a2a-go

To run the SUT manually:

# In the a2a-go repository
cd e2e/tck
go run sut.go sut_agent_executor.go

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines and docs/CLI_DESIGN_BEST_PRACTICES.md for design conventions to follow before adding or modifying commands.

License

Apache 2.0. See LICENSE.