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.

Quick Start

# Describe an agent — fetch its AgentCard, skills, and capabilities
a2acli discover --service-url http://localhost:9001

# Send a message and stream responses in real time
a2acli send "Generate a project plan" --service-url http://localhost:9001

# Send a message and get a single JSON result (for scripting and agents)
a2acli send "Generate a project plan" --service-url http://localhost:9001 -n --wait

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

Any platform — Go Install

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

From Source

git clone https://github.com/ghchinoy/a2acli.git
cd a2acli
make build

The binary is written to bin/a2acli.

Command Grammar

a2acli <verb> [noun] [positional-args] [flags]

Verbs map directly to A2A Protocol RPCs. Nouns are used where a verb spans multiple resource types (list tasks). Positional args are required IDs or message text. Flags are optional modifiers.

Pattern	Example	Notes
verb	a2acli discover	Verb only — single resource type
verb message	a2acli send "Hello"	Positional message text
verb id	a2acli get <taskID>	Positional task ID
verb noun	a2acli list tasks	Noun disambiguates resource

The agent URL is always a flag (--service-url / -u) rather than a positional argument. This enables named environment profiles in config — you rarely need to type a URL at all once configured.

Output modes are controlled by --output:

Mode	Flag	Use when
tui	default	Interactive terminal with streaming UI
text	--output text	Non-interactive, human-readable (CI logs, piped output)
json	--output json	Machine-readable NDJSON (scripts, agents)

-n / --no-tui is a backwards-compatible shorthand for --output json.

Commands

Commands are organized into four A2A-aligned groups: Discovery & Identity, Messaging & Tasks, Server & Mocking, and Client Configuration.

Discovery & Identity

describe — Inspect an Agent

Fetch and display an agent's AgentCard, registered skills, and security requirements. (Fetches via the standard A2A discovery endpoint.)

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

Messaging & Tasks

send — Send a Message

Send a message to initiate or continue a task. (Maps to the A2A Protocol's SendMessage RPC.)

a2acli send "Generate a project plan" --out-dir ./output/

By default, send streams real-time updates. Use --wait (-w) for a blocking call that returns the final result only.

Flag	Short	Description
--skill	-s	Target a specific skill on the agent
--wait / --sync	-w	Block until task completes (returns final JSON)
--out-dir	-o	Save artifacts to a directory
--file	-f	Save artifact to a specific filename
--instruction-file	-i	Path to a file with supplemental instructions

watch — Subscribe to a Task

Subscribe to an active task's event stream. (Maps to the A2A Protocol's SubscribeToTask RPC.)

a2acli subscribe <task_id> --out-dir ./output/

Flag	Short	Description
--out-dir	-o	Save artifacts to a directory as they arrive
--file	-f	Save artifact to a specific filename

get — Get Task Status

Retrieve the state and artifacts of a specific task. (Maps to the A2A Protocol's GetTask RPC.)

a2acli get <task_id> --out-dir ./output/

Flag	Short	Description
--out-dir	-o	Save artifacts to a directory
--file	-f	Save artifact to a specific filename

list — List Tasks

Query an agent for historical tasks. (Maps to the A2A Protocol's ListTasks RPC. The server must support history.)

a2acli list tasks --limit 10

Flag	Default	Description
--limit	10	Maximum number of tasks to return
--page-token	—	Pagination token for the next page

cancel — Cancel a Task

Cancel an active task. (Maps to the A2A Protocol's CancelTask RPC.)

a2acli cancel <task_id>

download — Download Artifacts

Download artifacts produced by a task to a local directory.

a2acli download <task_id> --out-dir ./downloads

Flag	Short	Description
--out-dir	-o	Directory to save artifacts to
--file	-f	Save artifact to a specific filename

Server & Mocking

serve — Run a Mock Agent

Spin up an A2A-compliant echo agent locally for testing and development.

a2acli serve --echo --port 9001

Flag	Default	Description
--port	9001	Listen port
--host	127.0.0.1	Bind address
--echo	—	Return the user's message as the response

Client Configuration

a2acli config    # Show active environment and config file location
a2acli version   # Print version information

Shell Completion

a2acli can generate completion scripts for bash, zsh, fish, and PowerShell.

zsh

a2acli completion zsh > "${fpath[1]}/_a2acli"

Or for a single session:

source <(a2acli completion zsh)

bash

a2acli completion bash > /etc/bash_completion.d/a2acli

Or for a single session:

source <(a2acli completion bash)

fish

a2acli completion fish > ~/.config/fish/completions/a2acli.fish

PowerShell

a2acli completion powershell | Out-String | Invoke-Expression

Configuration

a2acli supports named environments via an XDG Base Directory compliant config file at ~/.config/a2acli/config.yaml. This lets you switch between local, staging, and production agents without repeating URLs and tokens.

# ~/.config/a2acli/config.yaml
default_env: "local"

envs:
  local:
    service_url: "http://127.0.0.1:9001"
  staging:
    service_url: "https://staging-agent.internal.corp"
    token: "my-staging-auth-token"
  prod:
    service_url: "https://agent.example.com"
    token: "my-secure-prod-token"

Use the --env (-e) flag to select an environment:

a2acli send "Generate report" --env staging

Precedence: CLI Flags > Environment Variables > Config File > Defaults.

Environment variables follow the pattern A2ACLI_<FLAG> (e.g. A2ACLI_SERVICE_URL).

Global Flags

Flag	Description
-u, --service-url	Base URL of the A2A service (default: http://127.0.0.1:9001)
-t, --token	Authorization token
--auth	Authorization headers, e.g. Bearer … (repeatable)
--svc-param	Service parameters, e.g. key=value (repeatable)
-k, --task	Existing Task ID to continue (must be non-terminal)
-r, --ref	Task ID to reference as context
-n, --no-tui	Output JSON/NDJSON instead of the interactive TUI
-p, --protocol	A2A protocol version: 1.0.0 or 0.3.0 (default: 1.0.0)
--transport	Force transport: grpc, jsonrpc, or rest
-e, --env	Named environment from config file
-c, --config	Path to config file
-V, --version	Print version information

Example: auth and service parameters

a2acli send "Generate report" --service-url http://localhost:9001 \
  --auth "ApiKey secret-key-here" \
  --svc-param "tenant_id=123" \
  --svc-param "debug=true"

Agent & Automation

a2acli is designed to be driven by AI coding agents (Claude Code, Cursor, GitHub Copilot CLI) as well as shell scripts.

Non-Interactive Mode (-n)

The -n / --no-tui flag switches all output to newline-delimited JSON (NDJSON), giving scripts and agents a stable, parseable stream. It can also be set via A2ACLI_NO_TUI=true or NO_COLOR=true.

a2acli send "Write code" -n --wait

Transport Selection

a2acli auto-selects the best available transport based on the agent's advertised capabilities, in priority order: gRPC > JSON-RPC > REST. Override when needed:

a2acli send "Generate video" --transport grpc

When using --protocol 0.3.0, only jsonrpc is available. gRPC is disabled for legacy connections to prevent protobuf namespace conflicts.

Proactive Error Hints

On failure, the CLI emits a Hint: to assist automated recovery:

Error: failed to resolve AgentCard: connection refused
Hint: Ensure the A2A server is running at http://localhost:9001

Agent Skills

This repository ships an agentskills.io compliant skills/ directory. AI coding agents load these skills automatically and learn to use --no-tui and --wait for deterministic JSON output.

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