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.

Authentication And Guest Sessions

Registry agents use your Aion account. Run aio login or /login inside chat to sign in to the selected environment. An expired or rejected account asks you to log in again; it does not switch to a guest identity. Registry catalog discovery currently requires an account. Configured direct agent sources, including http://localhost:8000, use a separate guest bearer unless you provide explicit endpoint credentials. The client obtains that guest session from the selected Aion control plane, then sends requests directly to the agent. Signing in to the registry does not send your account bearer to a local server. Discovery, message requests and stream reconnects use the same source credential. Guest tokens last 30 days and renew during active use in their final seven days, preserving the session ID. There is no absolute lifetime limit. Temporary renewal failures retain a still-valid token and use bounded retry backoff; rate-limit responses honor Retry-After. No idle renewal timer keeps an unused client alive. The OS keychain stores guest credentials separately from account refresh tokens, scoped by control-plane URL, environment, source key and destination origin. npm and Python launches use separate keychain service names. Tokens are not stored in chat2.json or conversation files. Losing a keychain entry may create a fresh session next time; the client cannot recover the previous session’s access. When a held guest credential expires or is rejected, chat requires an explicit choice:

/sources
/session retry default-localhost-8000
/session new default-localhost-8000

Use retry for a temporary outage. Use new only when you want to replace that source’s guest identity. A new guest session cannot access the previous guest’s conversations. This does not delete those conversations. /clear starts a new conversation without replacing the guest identity. For an explicit endpoint in headless mode, opt in to replacement with:

aio run --url http://localhost:8000 --new-session "Hello"
aion chat run --url http://localhost:8000 --new-session "Hello"

An explicit --url has its own source key, separate from the default localhost source. Keep using the same source and launcher to reuse its guest identity. --token and --header apply only to the explicit source; credentials never follow a discovered cross-origin URL or redirect.

The selected control plane must serve /auth/anonymous-sessions. Client bearer delivery does not prove that an agent verifies it: SDK server verification and ownership enforcement are a separate rollout step. A guest bearer does not grant account-only GraphQL, file-upload or private Aion Chat access.

Python SDK CLI

Use the Python SDK CLI when you are working inside a Python SDK project. Install it from the Python SDK installation guide. aion chat launches the terminal UI bundled with the Python package, so Node.js 22+ must be on PATH. If you do not want the Python SDK at all, install the standalone npm package described below instead. Start interactive chat:

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:

aion chat

Target a different endpoint:

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

Target a specific agent through a proxy:

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

Send a headless message to a discovered agent:

aion chat run --agent @david "Hello"

Write raw A2A protocol output for a headless message:

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"

Guides

Core Concepts

Ions

Resources

Distributions

Tools

Other

Composer Controls

Authentication And Guest Sessions

Python SDK CLI

Options

Examples

Standalone npm Package

Options

Examples

​Composer Controls

​Authentication And Guest Sessions

​Python SDK CLI

​Options

​Examples

​Standalone npm Package

​Options

​Examples

Composer Controls

Authentication And Guest Sessions

Python SDK CLI

Options

Examples

Standalone npm Package

Options

Examples