Look up Handler commands

Handler’s command line is optimized for both humans and agents. Use text output interactively, JSON for scripts, and NDJSON for streaming event consumers.

Global options

Option	Description
`--version`	Show the version and exit.
`-v, --verbose`	Enable verbose logging.
`-d, --debug`	Enable debug logging.
`--output text/json/ndjson`	Select output format. Defaults to `text`.
`--quiet`	Suppress non-error output.
`--connect-timeout SECONDS/none`	HTTP connect timeout. Env: `HANDLER_CONNECT_TIMEOUT`.
`--read-timeout SECONDS/none`	HTTP read timeout for non-streaming calls. Env: `HANDLER_READ_TIMEOUT`.
`--write-timeout SECONDS/none`	HTTP write timeout. Env: `HANDLER_WRITE_TIMEOUT`.
`--pool-timeout SECONDS/none`	HTTP connection pool timeout. Env: `HANDLER_POOL_TIMEOUT`.
`--stream-read-timeout SECONDS/none`	HTTP read timeout for streaming calls. Defaults to `none`. Env: `HANDLER_STREAM_READ_TIMEOUT`.

Machine-readable metadata

Use these commands when generating wrappers, validating agent plans, or building docs from the installed CLI:

handler --output json schema

handler --output json describe message send

handler --output json describe task get

handler --output json describe server add

Core commands

`handler card get`

Retrieve an agent’s card.

handler card get --server my-agent

handler card get --url http://localhost:8000

Options: --url, -s, --server, -b, --bearer-env, -k, --api-key-env.

`handler card validate`

Validate an agent card from a URL, configured server, or local file.

handler card validate --server my-agent

handler card validate --file ./agent-card.json

Options: --url, --file, -s, --server, -b, --bearer-env, -k, --api-key-env.

`handler message send`

Send a message and receive a response.

handler message send --server my-agent --text "Hello"

handler --output json message send --server my-agent --text "Hello"

Options: --url, -s, --server, -t, --text, --stream, --json, --context-id, --task-id, -C, --continue, --push-url, --push-token, -b, --bearer-env, -k, --api-key-env, -H, --header.

`handler message stream`

Send a message and stream the response in real time.

handler message stream --server my-agent --text "Run the workflow"

handler --output ndjson message stream --server my-agent --text "Run the workflow"

Options match message send, except --text is required and streaming is always enabled. Every task command accepts the task ID positionally or with --task. The two forms are equivalent; passing two different IDs is an error.

`handler task get`

Retrieve task status.

handler task get task-123 --server my-agent

handler task get --server my-agent --task task-123 --history-length 10

Options: [TASK_ID], --url, -s, --server, --task, -n, --history-length, --params, -b, --bearer-env, -k, --api-key-env.

`handler task cancel`

Request cancellation of a task.

handler task cancel task-123 --server my-agent

`handler task resubscribe`

Resubscribe to a task’s SSE stream after disconnection.

handler task resubscribe task-123 --server my-agent

`handler task notification get`

Get the push notification configuration for a task.

handler task notification get task-123 --server my-agent

Options: [TASK_ID], --url, -s, --server, --task, -c, --config-id, -b, --bearer-env, -k, --api-key-env.

`handler task notification set`

Configure a push notification webhook for a task.

handler task notification set task-123 \
  --server my-agent \
  --webhook-url http://127.0.0.1:9000/webhook \
  --token local-secret

Options: --url, -s, --server, --task, --webhook-url, -t, --token, -b, --bearer-env, -k, --api-key-env.

Session commands

`handler session list`

List all saved conversation sessions.

handler session list

`handler session show`

Display saved conversation state.

handler session show --server my-agent

`handler session clear`

Clear saved conversation state for one agent.

handler session clear --server my-agent

Clear all saved conversation state.

handler session clear --all

Server commands

`handler server add`

Add a server to the global or repo-scoped configuration.

handler server add demo --url http://localhost:8000

handler server add prod --url https://agent.example.com --repository

Options include --url, --bearer-env, --api-key-env, --api-key-header, --cert, --key, --oauth2-token-url, --oauth2-client-id-env, --oauth2-client-secret-env, --oauth2-scope, --global, and --repository.

`handler server list`

List configured global and repo-scoped servers.

handler server list

`handler server show`

Show details for a configured server.

handler server show NAME

handler server show NAME --source repository

Options: --source repository/global.

`handler server remove`

Remove a server from the configuration.

handler server remove NAME

handler server remove NAME --repository

Options: --global, --repository.

`handler server validate`

Validate configured servers and default auth resolution.

handler server validate

`handler server run push`

Start a local webhook server for push notifications.

handler server run push

Interface and integration commands

`handler mcp`

Run a local MCP server exposing A2A protocol operations. Supports stdio, sse, and streamable-http.

handler mcp

`handler tui`

Launch the interactive terminal interface.

handler tui

`handler web`

Serve the TUI as a web application.

handler web

`handler docs`

Open the Handler documentation in your browser.

handler docs

`handler version`

Display the current version.

handler version

`handler update`

Update Handler to the latest published version.

handler update

`handler upgrade`

Alias for handler update.

handler upgrade

​Look up Handler commands

​Global options

​Machine-readable metadata

​Core commands

​handler card get

​handler card validate

​handler message send

​handler message stream

​handler task get

​handler task cancel

​handler task resubscribe

​handler task notification get

​handler task notification set

​Session commands

​handler session list

​handler session show

​handler session clear

​Server commands

​handler server add

​handler server list

​handler server show

​handler server remove

​handler server validate

​handler server run push

​Interface and integration commands

​handler mcp

​handler tui

​handler web

​handler docs

​handler version

​handler update

​handler upgrade