> ## Documentation Index
> Fetch the complete documentation index at: https://handler.alduncanson.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install Handler, start a local A2A server, send your first message, and save a server configuration.

# Get started with Handler

## Install Handler

Install Handler from the [PyPI package](https://pypi.org/project/a2a-handler/) as a `uv` tool:

```bash theme={null}
uv tool install a2a-handler
```

If you prefer not to install it globally, you can invoke Handler without installing:

```bash theme={null}
uvx --from a2a-handler handler --help
```

## 1. Start with the TUI

Open the interactive terminal UI:

```bash theme={null}
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:

```bash theme={null}
handler server run agent
```

Inspect the local A2A server's agent card:

```bash theme={null}
handler card get --url http://localhost:8000
```

Send your first message:

```bash theme={null}
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:

```bash theme={null}
handler server add demo --url http://localhost:8000
```

Store the server configuration with the current repository instead of your global config:

```bash theme={null}
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:

```bash theme={null}
handler server list
```

Show the resolved details for one server:

```bash theme={null}
handler server show demo
```

Validate configured servers and their auth references:

```bash theme={null}
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:

```bash theme={null}
handler message send --server demo --text "Hello"
```

Continue from Handler's saved session state:

```bash theme={null}
handler message send --server demo --text "Follow up" --continue
```

Inspect the saved session IDs:

```bash theme={null}
handler session show --server demo
```

See [Messages, tasks, and sessions](./guides/messages-tasks) 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:

```bash theme={null}
handler mcp
```

See [MCP server](./guides/mcp) for transport options and client setup.

## Open the docs from your terminal

Open the hosted Handler docs in your browser:

```bash theme={null}
handler docs
```

## Keep learning

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

<Columns cols={2}>
  <Card title="Read the guides" icon="book-open" href="/guides/tui" cta="Explore workflows" arrow>
    Learn Handler's TUI, CLI messaging, server configuration, authentication, MCP,
    and enterprise A2A workflows.
  </Card>

  <Card title="Open the CLI reference" icon="terminal" href="/reference/cli" cta="View commands" arrow>
    Look up Handler commands, flags, output modes, and machine-readable schema
    helpers for automation.
  </Card>
</Columns>