Skip to main content
Aion Chat terminal interface 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

ControlBehavior
EnterSend the message or select the active menu item.
Shift+EnterInsert a newline.
@Open the agent picker.
/Open the slash command picker.
EscDismiss the active menu or clear the draft.
Ctrl+CClear 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

OptionDefaultDescription
--url, --host, -uhttp://localhost:8000Agent or proxy URL to connect to.
--agent-idnoneAgent identifier for proxy-aware routing with an explicit endpoint.
--tokennoneBearer token for authenticated explicit endpoints.
--headernoneCustom HTTP header in key=value format. Repeatable.
--push-notificationsdisabledInclude local push notification configuration.
--push-receiverhttp://localhost:5000Push notification receiver URL.
--helpn/aShow help text.
aion chat run also supports headless one-shot messages:
OptionDefaultDescription
--agentnoneDiscovered agent handle, display id, identity id, or agent key.
--request-modesend-messagesend-message or streaming-message.
--response-modemessagemessage for rendered output or a2a for raw protocol JSON.
positional messagenoneMessage 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

OptionDefaultDescription
--url, --host, -uhttp://localhost:8000Agent or proxy URL to connect to.
--agent-idnoneAgent identifier for proxy-aware routing with an explicit endpoint.
--tokennoneBearer token for authenticated explicit endpoints.
--headernoneCustom HTTP header in key=value format. Repeatable.
--push-notificationsdisabledInclude local push notification configuration.
--push-receiverhttp://localhost:5000Push notification receiver URL.
--helpn/aShow help text.
--versionn/aPrint the package version.
aio run and aion-chat run also support headless one-shot messages:
OptionDefaultDescription
--agentnoneDiscovered agent handle, display id, identity id, or agent key.
--request-modesend-messagesend-message or streaming-message.
--response-modemessagemessage for rendered output or a2a for raw protocol JSON.
positional messagenoneMessage 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"