Aion Chat

Aion Chat is a terminal interface for chatting with A2A-compatible agents. It can run through the Python SDK CLI inside an Aion project, or as a standalone Node package installed from npm.

Composer Controls

Control	Behavior
`Enter`	Send the message or select the active menu item.
`Shift+Enter`	Insert a newline.
`@`	Open the agent picker.
`/`	Open the slash command picker.
`Esc`	Dismiss the active menu or clear the draft.
`Ctrl+C`	Clear the draft or exit when the draft is empty.

Python SDK CLI

Use the Python SDK CLI when you are working inside a Python SDK project or want to launch chat from poetry run aion chat. Install it from the Python SDK installation guide. Start interactive chat:

poetry run aion chat

By default, aion chat connects to http://localhost:8000. That default is useful when you are running a local Aion proxy or agent server with the Python SDK.

Options

Option	Default	Description
`--url`, `--host`, `-u`	`http://localhost:8000`	Agent or proxy URL to connect to.
`--agent-id`	none	Agent identifier for proxy-aware routing with an explicit endpoint.
`--token`	none	Bearer token for authenticated explicit endpoints.
`--header`	none	Custom HTTP header in `key=value` format. Repeatable.
`--push-notifications`	disabled	Include local push notification configuration.
`--push-receiver`	`http://localhost:5000`	Push notification receiver URL.
`--help`	n/a	Show help text.

aion chat run also supports headless one-shot messages:

Option	Default	Description
`--agent`	none	Discovered agent handle, display id, identity id, or agent key.
`--request-mode`	`send-message`	`send-message` or `streaming-message`.
`--response-mode`	`message`	`message` for rendered output or `a2a` for raw protocol JSON.
positional `message`	none	Message text. Use `-` to read stdin.

Examples

Connect to the default local endpoint:

poetry run aion chat

Target a different endpoint:

poetry run aion chat --url http://localhost:8000

Target a specific agent through a proxy:

poetry run aion chat --url http://localhost:8000 --agent-id support

Send a headless message to a discovered agent:

poetry run aion chat run --agent @david "Hello"

Write raw A2A protocol output for a headless message:

poetry run aion chat run --agent @david --response-mode a2a "Hello"

See Command Line Interface for the broader Python SDK CLI.

Standalone npm Package

Use the standalone npm package when you want the terminal chat client without installing the Python SDK. Install the standalone chat tool globally:

npm install -g @terminal-research/aion

Run the primary executable:

aio

By default, aio connects to http://localhost:8000. The package also installs an aion-chat alias:

aion-chat

Options

Option	Default	Description
`--url`, `--host`, `-u`	`http://localhost:8000`	Agent or proxy URL to connect to.
`--agent-id`	none	Agent identifier for proxy-aware routing with an explicit endpoint.
`--token`	none	Bearer token for authenticated explicit endpoints.
`--header`	none	Custom HTTP header in `key=value` format. Repeatable.
`--push-notifications`	disabled	Include local push notification configuration.
`--push-receiver`	`http://localhost:5000`	Push notification receiver URL.
`--help`	n/a	Show help text.
`--version`	n/a	Print the package version.

aio run and aion-chat run also support headless one-shot messages:

Option	Default	Description
`--agent`	none	Discovered agent handle, display id, identity id, or agent key.
`--request-mode`	`send-message`	`send-message` or `streaming-message`.
`--response-mode`	`message`	`message` for rendered output or `a2a` for raw protocol JSON.
positional `message`	none	Message text. Use `-` to read stdin.

Examples

Connect to the default local endpoint:

aio

Connect through a local proxy and select an agent:

aio --url http://localhost:8000 --agent-id onboarding

Send an authenticated request:

aio --url https://agent.example.com --token "$AION_TOKEN"

Add custom headers:

aio --header "X-Client=aion-docs" --header "X-Trace=demo"

Enable push notifications:

aio --push-notifications --push-receiver http://localhost:5000

Send a headless message to a discovered agent:

aio run --agent @david "Hello"

Write raw A2A protocol output for a headless message:

aio run --agent @david --response-mode a2a "Hello"

Usage

Core Concepts

Distributions

Tools

Other

Composer Controls

Python SDK CLI

Options

Examples

Standalone npm Package

Options

Examples

​Composer Controls

​Python SDK CLI

​Options

​Examples

​Standalone npm Package

​Options

​Examples

Composer Controls

Python SDK CLI

Options

Examples

Standalone npm Package

Options

Examples