Skip to main content

​
Get started with Handler

​
Install Handler

Install Handler from the PyPI package as a uv tool: 
uv tool install a2a-handler
If you prefer not to install it globally, you can invoke Handler without installing: 
uvx --from a2a-handler handler --help

​
1. Start with the TUI

Open the interactive terminal UI: 
handler tui
The TUI is the easiest place to browse cards, inspect tasks, and manage auth for an A2A server interactively.

​
2. Try the CLI

If you do not already have an A2A server available, start Handler’s bundled local agent in another terminal: 
handler server run agent
Inspect the local A2A server’s agent card: 
handler card get --url http://localhost:8000
Send your first message: 
handler message send --url http://localhost:8000 --text "hello"

​
3. Configure an A2A server

Handler can store A2A server definitions as configuration for repeated connections: the server URL, where the configuration lives, and any auth settings needed for Handler to connect as an A2A client. Save a global server configuration: 
handler server add demo --url http://localhost:8000
Store the server configuration with the current repository instead of your global config: 
handler server add demo --url http://localhost:8000 --repository
That creates or updates .handler/servers.toml at the root of the repository.

​
4. Inspect configured servers

List every configured server Handler can find: 
handler server list
Show the resolved details for one server: 
handler server show demo
Validate configured servers and their auth references: 
handler server validate

​
5. Keep the conversation going

Once you have a live task or saved conversation, the CLI can continue from the same context. Start or resume a conversation with the configured server: 
handler message send --server demo --text "Hello"
Continue from Handler’s saved session state: 
handler message send --server demo --text "Follow up" --continue
Inspect the saved session IDs: 
handler session show --server demo
See Messages, tasks, and sessions for the full flow.

​
Bridge Handler into MCP clients

If you want Amp, Pi, or another agent harness to use Handler’s A2A tools, add Handler to that tool’s MCP server configuration. Most MCP clients launch the server for you with this command: 
handler mcp
See MCP server for transport options and client setup.

​
Open the docs from your terminal

Open the hosted Handler docs in your browser: 
handler docs

​
Keep learning

Ready to go deeper? Choose the path that matches what you want to do next.

Read the guides

Learn Handler’s TUI, CLI messaging, server configuration, authentication, MCP, and enterprise A2A workflows.

Open the CLI reference

Look up Handler commands, flags, output modes, and machine-readable schema helpers for automation.