a2acli

README

A2A CLI

A standalone command-line client for interacting with Agent-to-Agent (A2A) services. It is fully compliant with the A2A Specification v1.0. It is built using the a2a-go v2 SDK and provides both an interactive streaming terminal UI and a scriptable non-interactive JSON mode.

🌟 Features

• A2A-Aligned Discovery: Inspect an agent's AgentCard, skills, and capabilities using protocol-native terminology (describe).
• Structured Messaging: Full lifecycle support for A2A tasks, including send (initiate), watch (subscribe), and get (retrieve).
• Agent-First Design: Built-in support for non-interactive JSON output, deterministic exit codes, and proactive "Hint" guidance for automated agents.
• Dynamic Transport Selection: Automatically selects the best available protocol (gRPC, JSON-RPC, or HTTP+JSON) based on advertised agent capabilities.
• Interactive TUI: A beautiful Bubble Tea interface for real-time streaming updates and artifact previews.
• Configuration Management: First-class support for XDG-compliant multi-environment configurations and auth token interception.

📦 Installation

1. Via Homebrew (macOS and Linux)

brew tap ghchinoy/tap
brew install a2acli

2. Via Install Script (Linux and macOS)

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

3. Via Go Install

If you have Go 1.25+ installed:

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

4. Via Source

Ensure you have Go 1.25+ installed.

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

This will produce the a2acli binary in the bin/ directory.

Alternatively, you can run it directly:

make run

🚀 Usage

Use the --help flag on any command to see the available options and A2A-aligned command groups.

a2acli --help

Global Flags

• -c, --config string: Path to a specific config file (default is ~/.config/a2acli/config.yaml)
• -e, --env string: Specific named environment to load from the config file
• -u, --service-url string: Base URL of the A2A service (default "http://127.0.0.1:9001")
• -t, --token string: Authorization token (if required by the agent)
• --auth strings: Authorization headers to send (e.g. 'Bearer ...', can be specified multiple times)
• --svc-param strings: Service parameters to send (e.g. 'key=value', can be specified multiple times)
• -k, --task string: Existing Task ID to continue a conversation/task (must be non-terminal)
• -r, --ref string: Task ID to reference as context (works for completed tasks)
• -n, --no-tui: Disables the interactive TUI and outputs JSON/NDJSON. Can also be set via A2ACLI_NO_TUI=true or NO_COLOR=true.
• -p, --protocol string: A2A protocol version (1.0.0 or 0.3.0). Defaults to 1.0.0. (Note: 0.3.0 only supports the jsonrpc transport).
• --transport string: Force a specific transport protocol (grpc, jsonrpc, httpjson). Defaults to auto-selection based on the agent's card.
• -V, --version: Print version information.

Example: Passing 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"

Configuration Management

a2acli supports managing multiple servers using an XDG Base Directory compliant configuration file. By default, it looks for ~/.config/a2acli/config.yaml.

You can define multiple named environments to easily switch between local, staging, and production agents without typing URLs and tokens repeatedly:

# ~/.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"

To view your currently active configuration context, run:

a2acli config

To run a command using a specific environment from your config file, use the --env (-e) flag:

a2acli send "Generate report" --env staging

Environment variables are also supported (e.g., A2ACLI_SERVICE_URL). The precedence is: CLI Flags > Environment Variables > Config File > Defaults.

Commands

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

1. Discovery & Identity

Describe Agent

Inspect the agent's identity, version, registered skills, and security requirements. (Fetches the AgentCard via the standard A2A discovery endpoint).

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

2. Messaging & Tasks

Send a Message

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

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

Synchronous vs. Streaming: By default, send streams real-time updates. Use --wait (or -w) to perform a blocking call that waits for the final result.

Watch a Task

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

a2acli watch <task_id>

Get Task Status

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

a2acli get <task_id>

List Tasks

Query an agent for a list of historical tasks it has processed. (Maps to the A2A Protocol's ListTasks RPC. Note: The server must support history).

a2acli list tasks --limit 10

Cancel a Task

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

a2acli cancel <task_id>

Download Artifacts

Download artifacts produced by a task to a local directory.

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

3. Server & Mocking

Start a Mock Server

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

a2acli serve --echo --port 9001

4. Client Configuration

View the active environment settings and config file location.

a2acli config
a2acli version

🤖 Agent & Automation

a2acli is designed with coding agents and automation in mind.

Non-Interactive Mode (-n)

Using the -n or --no-tui flag ensures that all output is emitted as parseable JSON/NDJSON. This is ideal for scripts and agents that need to consume A2A data programmatically.

a2acli send "Write code" -n --wait

Agent Skills (skills/)

This repository contains an agentskills.io compliant skills/ directory. These skills are designed to explicitly teach other AI coding agents (like Claude Code, Cursor, etc.) how to correctly interact with the a2acli tool programmatically.

By default, an agent will load these skills and understand that it must use the --no-tui and --wait flags when operating the CLI to ensure deterministic JSON outputs instead of hanging on interactive terminal UIs.

Proactive Error Hints

When a command fails (e.g., server down, invalid skill), the CLI provides a "Hint:" to assist with automated recovery.

Example Error:

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

Dynamic Transport Selection

Agents can automatically negotiate the most efficient transport protocol without manual intervention. By default, a2acli prioritizes protocols in the order: gRPC > JSON-RPC > HTTP+JSON.

For specialized environments, you can override this logic:

# Force gRPC for high-performance streaming
a2acli send "Generate video" --transport grpc

Note: When using --protocol 0.3.0, only the jsonrpc transport is available. The gRPC transport is explicitly disabled for legacy protocol connections to prevent protobuf namespace conflicts within the compiled binary.

🛠️ Development

• make build: Compiles the binary to bin/a2acli.
• make run: Builds and runs the CLI.
• make lint: Runs golangci-lint configured for Google Go standards.
• make test-e2e: Runs the end-to-end conformance tests.
• make clean: Removes the bin/ directory.

For details on how to build, publish, and release new versions of a2acli, see the Releasing Guide.

🏆 Testing Conformance (TCK)

To verify the CLI's compliance, you can test it against the official A2A Technology Compatibility Kit (TCK) System Under Test (SUT) server. The CLI supports both the legacy v0.3.0 and the current stable v1.0.0 specifications.

See the latest Conformance Report for current status.

The a2acli contains an automated end-to-end conformance test suite that will build the CLI, spin up the TCK SUT server locally, and run black-box tests asserting the machine-readable JSON output of the CLI.

Running Tests

Requirement: Running the end-to-end conformance tests requires the source code of the a2a-go SDK to be present on your local machine, as the tests dynamically spin up the TCK SUT server from that repository (https://github.com/a2aproject/a2a-go).

By default, the Makefile assumes the a2a-go repository is cloned at ../../github/a2a-go relative to the root of this project.

If you have it cloned elsewhere, you must override the A2A_GO_SRC variable when running make:

# Run all conformance tests (v1.0 and v0.3)
make test-e2e A2A_GO_SRC=/absolute/or/relative/path/to/a2a-go

To run the SUT manually for your own testing:

For A2A 1.0.0:

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

🤝 Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for guidelines on how to get involved.

We follow a set of CLI Design Best Practices to ensure the tool remains usable for both humans and agents. Please review these before submitting a PR that adds or modifies commands.

---

📄 License

This project is licensed under the Apache 2.0 License. See the LICENSE file for more details.