Reference

The tables on this page are generated from the code when the site is built, and each one is in alphabetical order.

Commands

Command	Arguments	Summary	Options
ahpd automation export <id>	id The automation's id.	Write an automation as an automation file	--vscode Write VS Code's automation file. --out PATH Write the file here instead of printing it.
ahpd automation import <file>	file The .automation.md file.	Make an automation from an automation file	--config-file PATH Read this instead of the file under the configuration directory. --folder PATH The folder it runs in, one this host serves. --vscode Read VS Code's automation file.
ahpd automation list		The automations this host holds
ahpd completion <shell>	shell bash, zsh, fish	Print the shell completion script (bash, zsh, fish)
ahpd config		Say where the configuration is, and what it says	Daemon options
ahpd configure		Ask for each setting a first install needs, and write it	--config-file PATH Read this instead of the file under the configuration directory.
ahpd paths add <folder>	folder The folder, by path.	Serve a folder	--config-file PATH Read this instead of the file under the configuration directory.
ahpd paths list		The folders this host serves	--config-file PATH Read this instead of the file under the configuration directory.
ahpd paths remove <folder>	folder The folder, by path.	Stop serving a folder	--config-file PATH Read this instead of the file under the configuration directory.
ahpd plugin config <name>	name The plugin, by its id or as plugins names it.	Show a plugin's options	--config-file PATH Read this instead of the file under the configuration directory.
ahpd plugin config <name> <key> <value>	name The plugin, by its id or as plugins names it. key One option. value The value: JSON when it parses, otherwise text.	Set one of a plugin's options	--config-file PATH Read this instead of the file under the configuration directory.
ahpd plugin config unset <name> <key>	name The plugin, by its id or as plugins names it. key One option.	Remove one of a plugin's options	--config-file PATH Read this instead of the file under the configuration directory.
ahpd plugin disable <name>	name The plugin, by its id or as plugins names it.	Turn a configured plugin off, keeping its entry and options	--config-file PATH Read this instead of the file under the configuration directory.
ahpd plugin enable <name>	name The plugin, by its id or as plugins names it.	Turn a configured plugin on	--config-file PATH Read this instead of the file under the configuration directory.
ahpd plugin install <name...>	name A package name. One or more.	Install a backend or another plugin into the configuration directory	--config-file PATH Read this instead of the file under the configuration directory. --no-enable--enable Install it without naming it in the file. --keep Take it out of the configuration and leave the package installed.
ahpd plugin list		What the configuration names, and what a run would load	Daemon options
ahpd plugin remove <name...>	name A package name. One or more.	Take a plugin out of the configuration, and uninstall it unless --keep	--config-file PATH Read this instead of the file under the configuration directory. --no-enable--enable Install it without naming it in the file. --keep Take it out of the configuration and leave the package installed.
ahpd plugin update <name...>	name all, or a package name. One or more.	Move the plugins named, or every installed one with all, to the version that fits this daemon	--force Install each package on its own, so one npm cannot install does not stop the others.
ahpd project add <id>	id The id a membership is written with.	Name a project	--config-file PATH Read this instead of the file under the configuration directory. --users FILE The people who may use this host. --title TEXT What a client shows for it. Without one, its id is what it shows.
ahpd project list		What this install names as a project	--config-file PATH Read this instead of the file under the configuration directory. --users FILE The people who may use this host.
ahpd project rm <id>	id The id to take out.	Take a project out of the file	--config-file PATH Read this instead of the file under the configuration directory. --users FILE The people who may use this host.
ahpd proxy list		The providers this proxy would call, and the model names that point at them	Daemon options
ahpd restart		Stop it and start it again with the line it was started with	--force Restart even while a turn is running.
ahpd start		Run it in the background and let go of it	Daemon options
ahpd status		Say whether one is running, and where	Daemon options
ahpd stop		Stop the one running in the background	Daemon options
ahpd team add <id>	id The id a membership is written with.	Name a team	--config-file PATH Read this instead of the file under the configuration directory. --users FILE The people who may use this host. --title TEXT What a client shows for it. Without one, its id is what it shows.
ahpd team list		What this install names as a team	--config-file PATH Read this instead of the file under the configuration directory. --users FILE The people who may use this host.
ahpd team rm <id>	id The id to take out.	Take a team out of the file	--config-file PATH Read this instead of the file under the configuration directory. --users FILE The people who may use this host.
ahpd usage		The pools this host was charged that the caller may see	Daemon options
ahpd usage <pool>	pool Which pool to read, as a record was charged to it.	What one pool spent today, this week and this month	Daemon options
ahpd user add <id>	id The identifier their credential answers with.	Add a person	--config-file PATH Read this instead of the file under the configuration directory. --users FILE The people who may use this host. --issuer NAME A provider of their own, rather than this host's default. --role NAME A role to give them. Repeatable. (repeatable) --membership TEAM[:PROJECT] What their work may be charged to, written team, team:* or team:project. Repeatable; user member replaces the whole list. (repeatable) --primary TEAM[:PROJECT] The one of those that work naming no scope of its own is charged to.
ahpd user list		Who is in the file	--config-file PATH Read this instead of the file under the configuration directory. --users FILE The people who may use this host.
ahpd user member <id> <entries...>	id Whose memberships to replace. entries A team, team:* or team:project. One or more.	What their work may be charged to	--config-file PATH Read this instead of the file under the configuration directory. --users FILE The people who may use this host. --unset Take every membership away, rather than naming one.
ahpd user primary <id> [entry]	id Whose primary to set or take away. entry One of their memberships, written team or team:project.	Where their work that names no team and project is charged	--config-file PATH Read this instead of the file under the configuration directory. --users FILE The people who may use this host. --unset Take their primary away, rather than setting one.
ahpd user rm <id>	id The identifier to take out.	Take a person out of the file	--config-file PATH Read this instead of the file under the configuration directory. --users FILE The people who may use this host.
ahpd user token <id>	id Whose credential to mint.	Mint a credential, shown once	--config-file PATH Read this instead of the file under the configuration directory. --users FILE The people who may use this host. --host ADDR Bind here. Default 127.0.0.1. Pass 0.0.0.0 to accept from other machines, which needs a token. --port N Listen here. Default 9187; 0 picks a free one. --url Print the whole ws:// URL a client can be given.
ahpd vault delete <name>	name The name to take out.	Take a name out
ahpd vault list		Every name this host keeps a secret under	--config-file PATH Read this instead of the file under the configuration directory.
ahpd vault set <name>	name The name to keep it under, as host:<name>, team:<team>/<name> or user:<id>/<name>.	Keep a value under a name

Daemon options

Key	Flag	Type	Description
advancedTools	--advanced-tools	boolean	Offer the tools that declare they need advanced permission, such as the computer's three.
archiveDirtyWorktree	--archive-dirty-worktree VALUE	keep | commit	What archiving a session does with a working tree that has uncommitted changes: keep leaves the tree, commit commits the changes on its branch and removes the tree.
automations	--automations VALUE	file | memory	file keeps automations beside the configuration and fires their schedules; memory keeps them until this process ends.
clientToolTimeoutMs	--client-tool-timeout-ms MS	integer	How long a call a client runs may wait. Default ten minutes; 0 waits for ever.
closedChats	--closed-chats VALUE	hidden | delete	What closing one chat of a session does to its conversation in the backend: hidden keeps it, delete removes it.
flag only	--config-file PATH	string	Read this instead of the file under the configuration directory.
connectionToken	--connection-token SECRET	string	Require this secret on every connection.
connectionTokenFile	--connection-token-file PATH	string	Require the secret in this file. A fresh one is written if the file is not there.
deltaWindowMs	--delta-window-ms MS	integer	How long a streamed delta waits for the next one before it is sent. Default 75; 0 sends every delta as it arrives.
host	--host ADDR	string	Bind here. Default 127.0.0.1. Pass 0.0.0.0 to accept from other machines, which needs a token.
http	file only	object | boolean	Serve the HTTP API: true under /api on the daemon's own listener, or an object whose port gives it a listener of its own and whose host binds that listener. Set in the configuration file only.
issuer	--issuer GITHUB|URL	string	An authorization server whose tokens are also accepted: github, or an OpenID Connect issuer.
mcpServers	file only	object	The MCP servers every session is offered, by the name a person gave them: a stdio server is a command an agent starts, and an http one is an endpoint it calls. An env or a header is a credential wherever it is, so each answers <set>. A session adds the servers of its own client plugins over these. Set in the configuration file only.
flag only	--no-cwd	boolean	Serve only the folders named above, and never ask about the folder this was started in. Refused when none is named.
flag only	--no-plugins	boolean	Load none, whatever the configuration file says.
origins	--origin URL	string[]	An origin this host also answers to, such as http://203.0.113.5:9187. Repeatable.
paths	--path DIR	string[]	A directory this host serves. Repeatable; the first is the default a client gets when it names none.
flag only	--plugin-option PLUGIN.KEY[.KEY...]=VALUE	string[]	Set one option of a plugin for this run, over the configuration file: <plugin>.<key>=<value>, where everything after the plugin is a key path set as deep into the plugin's options as it goes, a key on the way down that is not there made as it goes; the value is read as JSON when it parses and as text otherwise. Repeatable.
plugins	--plugin SPEC	string[]	A package, a path, or a package installed in the configuration directory, loaded at startup. Repeatable. Naming one runs its code in this process with this process's permissions: installing a plugin is the trust decision.
policies	file only	object	Whether the policies saying who may use which agent, model and computer are enforced: check refuses a session and a turn that no policy allows, naming the policy that refused it. Off by default, and the rows are written and listed either way. Set in the configuration file only.
port	--port N	integer	Listen here. Default 9187; 0 picks a free one.
proxy	file only	object	The providers this proxy calls and the model names that point at them: providers are keyed by the id a model entry names, and a model name is written <maker>/<name> with the entries serving it. An entry under a built-in id replaces it whole. A key is named by the environment variable holding it, never written here. sessionCalls is record (the default) or skip: whether a call made with a session's own token is policy-checked and recorded by the proxy. Set in the configuration file only.
pullRequestLookup	--pull-request-lookup VALUE	url | branch	How merged sessions learn the state of a pull request: url asks for each pull request by its page, branch asks for the pull requests of the session's branch.
resource	--resource URL	string	The https identifier this host advertises for its own sign-in. Default: derived from --host and --port.
routes	file only	object	Where the plugins' routes are served. Absent is the daemon's own port. A port gives them a listener of their own that serves nothing else, and a host binds that listener. Set in the configuration file only.
sessionResidencyLimit	--session-residency-limit COUNT	integer	How many sessions are loaded at most. Over it, the least recently used quiet session is let go. Default 10; 0 sets no limit.
sessions	--sessions VALUE	file | memory	Where the read and archived bits and a session's settings go.
sessionTools	--session-tools --no-session-tools	boolean	Offer the session tools. On by default; --no-session-tools offers none.
sessionToolsProviders	--session-tools-providers PROVIDER	string[]	Offer the session tools only to the sessions of these providers. Empty offers them to every provider.
shellEnv	file only	object	The environment every shell this host starts is given: a variable name set to its value, or to null to remove it, such as {"XDG_CONFIG_HOME": "/home/me/.config"}. Set in the configuration file only.
sleepAfterMinutes	--sleep-after-minutes MINUTES	integer	Minutes a session with nothing in hand stays loaded before its agent is let go. It wakes when something needs it. Default 30; 0 never lets it go for quiet.
flag only	--stdio	boolean	Serve one connection over stdin and stdout instead of binding a port. This is how a host runs inside a container for another host to carry: one line of JSON per frame, no token, and the connection is this host itself.
trustToken	--trust-token	boolean	A person's connection token authorizes them as well as admits them.
unownedAutomations	--unowned-automations VALUE	every | none	What an automation that names no owner wakes on. every is the default: an automation nobody made is nobody's work, so every session is offered to it. none wakes on nothing.
updateCheck	--update-check --no-update-check	boolean	Ask npm, in the background, whether a newer version exists. On by default; --no-update-check, NO_UPDATE_NOTIFIER, CI and "updateCheck": false in the configuration turn it off.
usage	file only	object	How a turn is written down: per "turn" writes one record when the turn ends, which is the default, and per "report" writes one record for every usage report a turn sends. timezone names, as Intl names one, the zone a day and a week start in, and is the system's own zone when it is absent. Set in the configuration file only.
users	--users FILE	string	The people who may use this host.
wire	--wire FILE	string	Append every frame, both directions, to this file as JSON lines.
withoutConnectionToken	--without-connection-token	boolean	Accept any connection. Only when the port is already reachable by nobody else.
worktreesRoot	--worktrees-root DIR	string	Keep every session worktree under this folder, as <dir>/<repo>/<name>. Default: <repo>.worktrees beside each repository.

Global options

Option	Description
-h, --help	Show help for the current command
--json	Emit stable machine-readable JSON
--no-color--color	Disable colour, as does a non-terminal or NO_COLOR
-q, --quiet	Print only identifiers or requested values
--refresh	Fetch the command surface --remote cached again.
--remote URL	Run the administration commands against a daemon over its HTTP API, rather than here.
--token SECRET env AHPD_TOKEN	The credential --remote presents. Defaults to AHPD_TOKEN.
--token-file PATH	Read the credential --remote presents from this file.
--verbose	Include diagnostics on stderr
--version	Print the version
--yes	Run a command that removes something without asking