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

Without -v or -d, Handler prints warnings and errors on stderr. Warnings cover a card that routes requests to a different origin than the one you configured and an agent that requires an extension you did not request.

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

Fetch the extended card an agent offers to authenticated clients:

handler card get --server my-agent --extended

Options: --url, -s, --server, --extended, -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"

Attach a file (a local path is sent inline, an http(s) URL by reference) and structured data:

handler message send --server my-agent --text "Review this" --file ./report.pdf --data '{"k": "v"}'

Options: --url, -s, --server, -t, --text, -f, --file, --data, --stream, --json, --context-id, --task-id, -C, --continue, --accept, --history-length, --no-wait, --save-artifacts DIR, --push-url, --push-token, -e, --extension, -b, --bearer-env, -k, --api-key-env, -H, --header. --file, --data, --accept, --extension, and --header are repeatable. --text is optional when a file or data part is attached. --no-wait and --stream are mutually exclusive.

`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 that --stream and --no-wait do not apply; streaming is always enabled. Every task command that takes a task ID accepts it positionally or with --task. The two forms are equivalent; passing two different IDs is an error.

`handler task list`

List the agent’s tasks, following pagination to the end.

handler task list --server my-agent

handler task list --server my-agent --status input-required --context-id ctx-123

Options: --url, -s, --server, --context-id, --status, --page-size, -n, --history-length, --include-artifacts, -b, --bearer-env, -k, --api-key-env. --status takes submitted, working, completed, failed, canceled, input_required, rejected, or auth_required, with hyphens accepted. --page-size must be between 1 and 100; every page is fetched regardless. A listing cut short by a misbehaving server is marked truncated in all three output formats.

`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. Without --config-id, the task’s single config is used; a task with several configs needs one named.

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

handler task notification get task-123 --server my-agent --config-id cfg-123

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.

`handler task notification list`

List a task’s push notification configs, following pagination to the end. Tokens are redacted in the output.

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

Options: [TASK_ID], --url, -s, --server, --task, --page-size, -b, --bearer-env, -k, --api-key-env.

`handler task notification remove`

Remove a push notification config from a task. The config is listed first, so an ID that does not exist fails clearly.

handler task notification remove task-123 --server my-agent --config-id cfg-123

Options: [TASK_ID], --url, -s, --server, --task, -c, --config-id (required), -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, --basic-username, --basic-password-env, --api-key-env, --api-key-header, --cert, --key, --oauth2-token-url, --oauth2-client-id-env, --oauth2-client-secret-env, --oauth2-scope, --oidc-issuer-url, --oidc-client-id-env, --oidc-client-secret-env, --oidc-scope, -H/--header (repeatable, Name: Value, sent on every request), --global, and --repository. See Authentication for the flags each scheme needs.

`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

Require the notification token the agent was given, and reject deliveries without it:

handler server run push --port 9001 --token local-secret

Options: --host, --port, --token.

Interface and integration commands

`handler mcp`

Run a local MCP server exposing thirteen A2A tools for cards, messages, tasks, push notifications, and sessions. Supports stdio, sse, and streamable-http; see MCP server for the tool list.

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 list

​handler task get

​handler task cancel

​handler task resubscribe

​handler task notification get

​handler task notification set

​handler task notification list

​handler task notification remove

​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