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 SDK and provides both an interactive streaming terminal UI and a scriptable non-interactive JSON mode.

Features

• Agent Discovery: Describe the capabilities and skills of an A2A agent using the describe command.
• Streaming Invocations: Send messages and instructions to an agent and see real-time streaming updates, tool uses, and status messages using the invoke command.
• Task Resumption: Re-attach and listen to an ongoing active task using the resume command.
• Status Queries: Retrieve the current status, metadata, and artifacts of a specific task using the status command.
• Artifact Management: Save produced artifacts and data parts directly to your local file system.

Installation

1. Via Go Install (Recommended)

If you have Go 1.25+ installed, you can easily install the CLI globally via go install:

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

2. Via Install Script

Alternatively, you can run the provided install script to download and install the latest pre-compiled binary:

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

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

a2acli --help

Global Flags

• -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)
• -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)
• --no-tui: Disables the interactive BubbleTea TUI and outputs JSON/NDJSON (useful for CI/CD and scripting). Can also be set via A2ACLI_NO_TUI=true or NO_COLOR=true.

Commands

Describe Agent

Inspect the agent's capabilities and registered skills:

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

Invoke a Skill

Send a message to the agent. This opens an interactive TUI that streams the agent's responses and tool executions.

a2acli invoke "Please calculate the fibonacci of 10" --service-url http://localhost:9001

You can also pass supplemental instructions via a file:

a2acli invoke "Analyze this data" --instruction-file ./instructions.txt

To target a specific skill:

a2acli invoke "Use the calculator" --skill "calc_skill"

To save artifacts generated by the agent:

a2acli invoke "Generate a report" --out-dir ./output/

Resume a Task

If you disconnected from a long-running task, you can resume listening to its event stream:

a2acli resume <task_id> --service-url http://localhost:9001

Check Task Status

Retrieve the current state of a task without streaming:

a2acli status <task_id> --service-url http://localhost:9001

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.

Testing Conformance (TCK)

To verify the CLI's v1.0 compliance, you can test it against the official A2A Technology Compatibility Kit (TCK) System Under Test (SUT) server.

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.

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:

make test-e2e A2A_GO_SRC=/absolute/or/relative/path/to/a2a-go

To run the SUT manually for your own testing:

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

Before starting work on a new feature or significant change, please open an issue to discuss your proposed approach with the maintainers. This helps ensure your contribution aligns with the project's goals and prevents duplicated effort or wasted work.

---

📄 License

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