Appearance
CLI
Every command, as ahpc help prints it. This page is built from the same text, so it matches the installed version.
For the flags of the screen, see Screen. For what each command is for, see the subject pages.
ahpc - drive an agent host from a shell
ahpc [--host ws://…] <command> [args] the screen is 'ahpc' with no command
Sessions
session list the catalogue, newest first [--archived] [--json]
[--limit N] [--cursor C] reads one page
session show <uri> what the host says about one [--full] [--json]
session new start one [--agent P] [--cwd DIR] [--trust]
[--set k=v]… [--json]
session rm <uri> dispose it
session history <uri> its turns [--all] [--full] [--json]
session config <uri> the schema and what is in force [--json]
session set <uri> <k> <v> change one config key
session read <uri> mark read [--unread]
session archive <uri> put it away [--undo]
session customizations <uri> skills, prompts, agents, servers [--json]
session export <uri> the whole session as one document
[--json] [--markdown]
session toggle <uri> <id> turn one on [--off]
Turns
prompt <uri> <text> say it and stream the answer [--model M] [--json]
[--queue | --steer] where a turn is running
exec <text> a session, one turn, and dispose it
[--agent P] [--cwd DIR] [--trust]
[--model M] [--json]
cancel <uri> stop the running turn
queue <uri> <text> say it after the one running [--model M]
unqueue <uri> <id> take it back
Answering
watch <uri> BLOCK until something wants a person, print, exit
[--until turn|input|idle] [--timeout S] [--json]
confirm <uri> <toolCallId> approve a tool call [--deny] [--option ID]
answer <uri> <requestId> answer a question [--field k=v]… [--reject]
Chats
chat list <uri> the conversations in a session [--json]
chat new <uri> [text] another one beside it
chat show <chatUri> what the host says about one [--full] [--json]
chat history <chatUri> its turns [--all] [--full] [--json]
chat rm <chatUri> close one
The harness
agents what it serves, and each one's models [--json]
models every model, by harness [--json]
commands what a slash offers [--json]
customizations skills, prompts, agents and MCP servers,
before any session exists [--kind k] [--json]
completions <uri> <text> what the host would complete [--offset N] [--json]
Changes and files
changes <uri> the files a session touched [--json]
[--list] [--scope s] [--<variable> v]
[--reviewed f] [--unreviewed f]
[--operations] what may be done to it
[--run id] [--file f] [--yes] do one of them
[--message m] for commit
[--title t] [--body b] [--draft] for create-pr
[--list] every changeset it offers
[--scope <name>] one of them, e.g. turn
[--turnId <id>] what a chosen scope still needs
[--reviewed <file>] tick one off, repeatable
[--unreviewed <file>] and clear one
content <uri> <file> one of them, in full
resource list <uri> a directory the host serves [--json]
resource read <uri> a file on the host
resource stat <uri> what it is, without reading it [--json]
resource write <uri> [file] from a file, or from stdin [--create-only]
guarded by the file's etag unless [--force]
resource rm <uri> delete it [--recursive]
resource mkdir <uri> make a directory
resource mv <uri> <to> move it [--fail-if-exists]
resource cp <uri> <to> copy it [--fail-if-exists]
Automations
automation list what runs on its own [--json]
automation show <uri> one of them [--json]
automation triggers what this host can trigger on [--json]
automation runs <uri> its history, every page [--json]
automation run <uri> start it now
automation enable <uri> switch it on
automation disable <uri> switch it off
automation rm <uri> forget it
The host's own log
logs what the daemon is saying [--level L] [--follow]
Signing in
auth what this host protects [--json]
auth <resource> push a token [--token T] [--expires-in S]
or set AHPC_TOKEN_<RESOURCE>, or pipe one in
Terminals
terminal list what is running [--json]
terminal new open a shell [--cwd DIR] [--trust] [--name N]
terminal rm <uri> kill it
terminal send <uri> <text> type into it
terminal watch <uri> follow its output [--timeout S]
Recording
--wire <file> append every frame, both directions, as JSON
lines: { at, from, peer, frame }, for
'npm run wire' to check against the protocol.
AHPC_RECORD=<file> is the same, from a shell
wire <file> watch a capture as it is written, from either
end: one row per frame, a row opens to the
frame. Off a terminal, one line per frame
[--follow] [--filter text] [--json]
Serving these sessions to something else
mcp MCP on stdin and stdout, for a client that
launches this process
serve the same tools on a socket, shared
[--serve-host H] [--serve-port N] [--serve-token T]
[--serve-origin URL]… a browser page allowed in
/mcp is MCP; /api/<tool> is plain JSON
both take [--mcp-tools G,…] extra tool groups to serve, on top of the
sessions ones: resources, terminals,
automations, changes, or all
Anything else
dispatch <uri> <type> send one action verbatim [--field k=v]… [--chat]
<uri>, anywhere above a session URI, or the agent-host-session://
link the host's session tools answer with
status what this client is connected to [--json]
--version what version this is
help this
The host
--host <url> ws://host:port, or AHPC_HOST, or the config file
--token <tkn> a bearer token for it, or AHPC_TOKEN, or the config file
--connection-token-file <p>
read the token from this file, which is what the host
writes when it is given the same flag
--config-file read this instead of the one below
(none) the scripted host, which needs nothing installed
Configuration
config where the file is, and what is in force [--json]
Output is for reading. --json is the same answer for a program.