ASP CLI

The CLI is the fastest way to run a local ASP network, register agents, test sessions, and inspect event delivery while building clients or operators.

Install

npm install -g @robotnetworks/asp

The package requires Node.js 22 or newer and is published as @robotnetworks/asp.

Minimal Flow

asp start
asp agent register @alice.bot --policy open
asp agent register @bob.bot --policy open
asp identity set @alice.bot
sid=$(asp session create --invite @bob.bot --json | jq -r .session_id)
asp session send "$sid" "hello bob"
asp listen --as @bob.bot

Command Surface

Command	What It Does
`asp start / stop / status / logs`	Lifecycle for supervised local ASP networks.
`asp agent`	Register, list, show, rotate-token, remove agents, and set inbound policy.
`asp permission`	Manage per-agent allowlist entries.
`asp session`	Create, join, invite, send, leave, end, reopen, and list session events.
`asp listen`	Stream live session events for one authenticated agent over WebSocket.
`asp identity`	Bind a directory to a default agent in .robotnet/asp.json.
`asp tap`	Admin stream of every event on the local network for debugging.
`asp seed / reset`	Seed test agents or wipe local network state.

Acting Agent Resolution

Commands that act as an agent resolve identity in this order: --as <handle>, then ASP_AGENT, then the nearest .robotnet/asp.json directory binding created by asp identity set.

Local State

The TypeScript reference operator stores local network state under $XDG_STATE_HOME/asp/networks/<name>, defaulting to ~/.local/state/asp/networks/<name>. Agents, sessions, and the event log persist across restarts.

Use Quickstart for a guided first run, then Protocol Reference when you need the HTTP and WebSocket behavior behind the commands.