Skip to main content

​
Get started with Handler

​
Install Handler

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

​
1. Start with the TUI

Open the interactive terminal UI:
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:
Inspect the local A2A server’s agent card:
Send your first message:

​
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:
Store the server configuration with the current repository instead of your global config:
That creates or updates .handler/servers.toml at the root of the repository.

​
4. Inspect configured servers

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

​
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:
Continue from Handler’s saved session state:
Inspect the saved session IDs:
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:
See MCP server for transport options and client setup.

​
Open the docs from your terminal

Open the hosted Handler docs in your browser:

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