All docs

Operate

Command line

The conventions of ail and all its subcommands. Agents and you use the same ones.

Apart from its two resident modes, desk and daemon, every ail subcommand is a command line for getting things done through the Desk. An agent in a session types ail <subcommand> in its own shell tool; you use the same subcommands in a terminal on any Client.

Conventions

Starting and pairing

Command What it does
ail desk --listen <address:port> --data <data directory> Run the Desk
ail desk pairing --client-id <id> Issue a pairing code on the Desk's machine
ail desk authz list|allow|revoke List, add or revoke authorization rules
ail pair --desk <address> --code <pairing code> --client-id <id> Pair a Client
ail daemon --plugins <plugin directory> Run the Daemon
ail version, ail status The version; this Client's id, the Desk's address, and whether it is connected
ail setup desk|daemon|upgrade|rollback|remove Install as a resident service, upgrade, roll back, remove; see Install and upgrade

Inside a session

Command What it does
ail whoami The principal of this call and its Client; a session also gets its environment, run and role
ail shell [--target <Client>] [--shell powershell|bash] … Non-interactive execution; see Across machines
ail sync, ail get, ail put Remote workspaces: sync the mirror, fetch and place single files
ail prompt --out <file> Write this session's first message to a file
ail doc list, ail doc get <name> Documents and templates in the official plugin, fetched when needed
ail worktree start|finish|drop|leftovers Changes; see Workflows and the engine
ail call <role> "<what to do>" Call a tool role; returns a call number at once
ail report review|present|ask|preview|withdraw Push reports, ask, preview, withdraw; see Reports
ail op <operation id> How a background operation is doing

Sessions

Command What it does
ail session new --client <Client> --cwd <directory> --harness <id> Open a session and print its id. Add --harness-client to start the harness on another Client
ail session list List sessions
ail session show <session> The events of a session
ail session close <session> Close its adapter process; a later message reconnects it

Runs

Command What it does
ail dispatch --repo <repo id> --intent <intent> --title "<title>" --request-file <file> Start a run and print its id
ail continue <run> Continue a run
ail send <run or session> --request-file <file> Send a message, optionally with images
ail stop <run or session> Cancel the turn in progress
ail archive <run> Archive; on a run that has not ended, this terminates it
ail result <run or session> The full text of the latest report
ail board The board
ail map <repo id> Maps
ail log runs|show|stats The run log
ail journal record|list Write a Journal entry, list the Journal
ail router status Where the Router session is and the current contract version

Plugins and repositories

Command What it does
ail plugin sync Sync the main repository and every registered repository
ail plugin status Which Client each repository is on, the commit checked out, and whether there is uncommitted work
ail repo list, ail repo find <keyword> List and find registered Repos
ail repo add, ail repo update, ail repo archive Register, change a registration, archive

Who may use what

Subcommand Who may use it
dispatch, continue, send, stop, archive The Router session and you
session new, session close You
prompt, worktree, call, report, sync, get, put Sessions only: they act on the session that calls them
shell --target According to the authorization rules
Everything else Any principal

A call that is not allowed returns AUTHZ_DENIED.