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 send command.
• Task Resumption: Re-attach and listen to an ongoing active task using the watch command.
• Status Queries: Retrieve the current status, metadata, and artifacts of a specific task using the get 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

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

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

Describe Agent

Inspect the agent's capabilities and registered skills. (This fetches the AgentCard via a standard HTTP GET request to the Agent's root or well-known URL).

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

Send a Message

Send a message to the agent. This opens an interactive TUI that streams the agent's responses and tool executions. (Maps directly to the A2A Protocol's SendMessage RPC method).

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

You can also pass supplemental instructions via a file:

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

To target a specific skill:

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

To save artifacts generated by the agent:

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

Synchronous (Blocking) Execution: If you are writing scripts or testing and only care about the final result rather than the intermediate streaming events, you can use the --wait (or --sync) flag. This maps directly to setting the Blocking: true parameter within the A2A SendMessage payload, instructing the server to hold the request open and natively return the final Task status natively.

# Combine with --no-tui for pure JSON output of the final task state!
RESULT=$(a2acli send "Tell me a joke" --wait --no-tui)

Watch a Task

If you disconnected from a long-running task, you can resume listening to its event stream. (Maps directly to the A2A Protocol's SubscribeToTask RPC method).

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

Get Task Status

Retrieve the current state of a task without streaming. (Maps directly to the A2A Protocol's GetTask RPC method).

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

If the task has completed and produced artifacts, you can save them locally during a get:

a2acli get <task_id> --out-dir ./downloads/
a2acli get <task_id> --file report.md

Download / Retrieve Artifacts

A convenience wrapper over the get command explicitly meant for downloading artifacts. By default, this saves artifacts to the current directory if no --out-dir or --file is provided.

a2acli download <task_id>
a2acli retrieve <task_id> --file final_report.json

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