cli · pastor docs

cli every command, argument and flag

pastor is one binary with a command per area. Below the shared behaviour, this page lists every command, argument and flag with the help --help prints; it is generated from the binary, so it cannot drift from it.

shared behaviour #

Every list and describe takes --json, and so do pastor queue, pastor serve status and pastor head show. Scripts and agents should read ids and states from it rather than parse the tables.
The commands that change something and answer with a result take --json too: task run, retry, priority, close, prune, send, done, queue move and tick.
-w, --wide on task list, machine list, flock list, job list, orchestrator list and connector list adds a DESCRIPTION column, cut to the terminal’s width. On task list it adds RESULT too: how each task’s last round ended.
--head <DEST> on any command uses the head at that ssh destination for this one command. See a remote head.
A runtime error is one JSON object on stderr, {"code": ..., "message": ...}, with exit 1. A malformed command line prints usage text with exit 2.
pastor --skill prints the guide for coding agents that drive pastor.

A task is named t-12 or just 12. A machine is named as flock.toml names it. A job or orchestrator is its file name without .toml.

pastor #

run coding agents on machines you own

argument	does	default
`--skill`	Print the agent skill (SKILL.md) for this version and exit
`--head <DEST>`	Use the head at this ssh destination for this command (over PASTOR_HEAD and client.toml)

serve #

Run the daemon in the background: scheduler, machine channels, dispatch. With a head set on another machine, run headless: this machine’s jobs and hooks, and the head’s tasks for it as a pull machine

A bare pastor serve starts the head in the background, logging to serve.log in the state dir, and returns once it answers; –foreground keeps it in this terminal. One started by systemd or launchd stays in the foreground either way.

argument	does	default
`-f, --foreground`	Run in this terminal until a signal, logging to stderr; what a service runs

pastor serve stop #

Stop the pastor serve running here (SIGTERM); agents keep running

pastor serve status #

Whether pastor serve runs here: head or headless, pid, version, service, log

argument	does	default
`--json`	Print as a JSON object

task #

Manage tasks

pastor task run #

Create a one-off task and dispatch it

argument	does	default
`<PROMPT>`	What the agent is asked to do (or –prompt-file)
`--prompt-file <PATH>`	Read the prompt from this file on this machine (’-’ for stdin); it spares long prompts the shell’s quoting
`--repo <PATH>`	The repo the agent works in: a path on the machine that runs the task, not on this one
`--flock <FLOCK>`	Only this flock’s machines take the task (default: the flock of –machine, else the default flock)
`--machine <MACHINE>`	Run it on this machine (a name from flock.toml) instead of any free one
`--agent <AGENT>`	The agent command to start, like claude or codex (default: the machine’s, else its flock’s, else `[defaults]`, else claude)
`--agent-arg <ARG>`	One argument for the agent; repeat it, in order, for more. Replaces the flock’s and `[defaults]` agent_args. The next word is always the value, dashes and all
`--model <NAME>`	Run this model, a name from `[models]` in pastor.toml; its args go before the agent’s (default: the flock’s, else the machine’s, else `[defaults] model`, else none)
`--fallback <NAMES>`	The models the task may fall back to, in order: names from `[models]` in pastor.toml, comma separated (default: the machine’s, else the flock’s, else `[defaults] fallback`, else none)
`--no-fallback`	Fall back to no other model, whatever the machine, flock or `[defaults]` say
`--priority <LEVEL>`	Queue at this level: low, normal, high or critical; dispatch takes higher levels first (default: the flock’s, else the pinned machine’s, else `[defaults] priority`, else normal)
`--preempt`	A critical task only: on a full machine, pause the newest low Claude task there (its session resumes when a slot frees) and take its slot
`--now`	Start at once on –machine (which it needs), skipping the queue and running past that machine’s max_agents, job slots, burst and flock number; meant for a person at the CLI, and refused from a task or an orchestrator as a guard against mistakes, not a boundary
`--profile <NAME>`	Run under this permission profile, built in or from `[profiles]` in pastor.toml: a Claude agent gets its allow and deny lists and never asks (default: the flock’s, else the machine’s, else `[defaults] profile`, else none)
`--worktree`	A git worktree per task, branched from –repo (so it needs –repo)
`--branch <BRANCH>`	Branch for the worktree (needs –worktree; a plain workspace has no branch)
`--tag <TAGS>`	Only a machine with this tag takes the task; repeat for more, and it needs them all
`--timeout <TIMEOUT>`	Mark the task stale once it has run this long (30m, 2h; default: the flock’s, else `[defaults] timeout`)
`--label <TEMPLATE>`	Label template of the workspace pastor makes for the task, with {{ task.id }}, {{ flock }}, {{ machine }}, {{ job }} and {{ item.key }} (default: the flock’s `label`, else `[defaults] label`, else {{ flock }}/{{ task.id }}). The agent stays t-N
`--keep-pane`	Keep the agent’s pane open once the task is done, failed or stale, until `pastor task close`, so you can go on talking to the agent; a kept done task holds no slot (default: the flock’s `keep_pane`, else `[defaults] keep_pane`, else no)
`--place <PLACE>`	Where the agent’s pane goes: repo (under the repo it works on), own (its own workspace), pastor (the `pastor` workspace) or pane:<workspace> (default: the flock’s, else `[defaults] place`, else repo)
`--role <ROLE>`	What the agent may change through the head: agent (read, and end its own task) or orchestrator (also run, retry, send to and close tasks and enable and disable jobs). Only a person may start an orchestrator, never a task (one of `agent`, `orchestrator`)	`agent`
`--summary <MODE>`	Ask the agent for a summary when it finishes (ask), also fail the task if it stops without one (require), or neither (off) (default: the flock’s `summary`, else `[defaults] summary`, else ask) (one of `ask`, `require`, `off`)
`--description <TEXT>`	One line on what the task is about, for `task list --wide` and `describe` (default: the prompt’s first line)
`--json`	Print as a JSON object

pastor task list #

List live tasks across the flock; –all adds finished ones

argument	does	default
`--job <JOB>`	Only tasks from this job (omit for one-off `run` tasks)
`--flock <FLOCK>`	Only tasks of this flock
`--machine <MACHINE>`	Only tasks on this machine
`--blocked`	Only blocked tasks, needing a human
`--done`	Only done tasks
`--all`	Every task, finished ones too (done, failed, stale, closed)
`-w, --wide`	Add RESULT and DESCRIPTION columns, the second cut to the terminal’s width
`--json`	Print as a JSON array of full task records

pastor task describe #

One task in full: state, machine, agent, the models it moved through on usage limits, prompt, error, summary

argument	does	default
`<TASK>`	A task, like t-12 or 12
`--all-summaries`	Show every round’s summary, not only the last
`--json`	Print as a JSON object

pastor task read #

Read recent output from a task’s pane

argument	does	default
`<TASK>`	A task, like t-12 or 12
`--lines <LINES>`	How many lines from the bottom of the pane	`40`

pastor task attach #

Attach to a task’s agent terminal (ctrl+b q detaches); a closed Claude task’s session reopens in a new pane

argument	does	default
`<TASK>`	A task, like t-12 or 12

pastor task retry #

Re-dispatch a failed or stale task as a new task (retry_of points back)

argument	does	default
`<TASK>`	A task, like t-12 or 12: a failed or stale one
`--place <PLACE>`	Where the new task’s pane goes instead of the old one’s: repo, own, pastor or pane:<workspace>
`--json`	Print as a JSON object

pastor task priority #

Put a queued task at another level: low, normal, high or critical

argument	does	default
`<TASK>`	A task, like t-12 or 12: a queued one
`<LEVEL>`	Its new level: low, normal, high or critical
`--preempt`	Critical only: let the task pause the newest low Claude task on a full machine to start; without it the task’s flag goes
`--json`	Print as a JSON object

pastor task close #

Close tasks’ panes (and with –remove-worktree their worktrees), or orphaned agents

argument	does	default
`<TASK>`	Tasks, like t-12 or 12, or orphaned agents named like one; each is closed in turn, and one that fails does not stop the rest
`--remove-worktree`	Remove each task’s worktree too (refused if it has uncommitted changes)
`--json`	Print as a JSON object, or an array of them for several tasks

pastor task prune #

Delete old finished tasks; their items stay seen

argument	does	default
`--done`	Prune done tasks
`--failed`	Prune failed tasks
`--closed`	Prune closed tasks
`--older-than <DURATION>`	Only tasks that finished longer ago than this (30m, 12h, 3d) (required)
`--json`	Print as a JSON object

pastor task send #

Type text or press keys in a live task’s agent, to answer what it is waiting on

argument	does	default
`<TASK>`	A task, like t-12 or 12: a live one (starting, running or blocked)
`<TEXT>`	Text to type into the agent, followed by Enter
`--key <KEY>`	A named key to press after the text (Enter, Down, esc, ctrl+c); repeat for more, in order
`--no-enter`	Type the text without pressing Enter after it
`--trust`	Accept the agent’s folder-trust prompt with its trust keys, and trust the task’s repo on its machine from now on
`--json`	Print as a JSON object

pastor task done #

Mark a task done, its pane to close after close_done_after; an agent may end its own

argument	does	default
`<TASK>`	A task, like t-12 or 12: the one to end (default: the task this pane runs, from PASTOR_TASK)
`--summary <TEXT>`	What you did, its first line the outcome: done, partial, blocked or nothing to do (kept to 2,000 characters)
`--summary-file <PATH>`	Read the summary from a file, or - for stdin
`--json`	Print as a JSON object

queue #

The queued tasks in the order they will start, and why each waits; move one

argument	does	default
`--flock <FLOCK>`	Only the tasks waiting in this flock
`--machine <MACHINE>`	Only the tasks pinned to this machine
`--json`	Print as a JSON array

pastor queue move #

Put a queued task elsewhere in the queue; it takes the level of where it lands

argument	does	default
`<TASK>`	A task, like t-12 or 12: a queued one
`--top`	First in the queue, lifted to the first task’s level if that is higher
`--before <TASK>`	Just ahead of this queued task
`--after <TASK>`	Just behind this queued task
`--to <N>`	At this position, as `pastor queue` numbers it (1 is first)
`--json`	Print as a JSON object

machine #

Manage the machines and which flock each is in

pastor machine add #

Add a machine to flock.toml, reached over ssh, locally or by a command

argument	does	default
`<NAME>`	The name pastor calls it by, in tasks, jobs and agent names
`<SSH>`	How ssh reaches it, like user@pi-1 (or an ssh config Host)
`--local`	This machine itself, through herdr’s local socket; no ssh
`--command <COMMAND>`	Developer option: the bridge command as one string, split on whitespace (`--command "fake-herdr --connect /tmp/h.sock"`). Words containing spaces go in flock.toml by hand
`--session <SESSION>`	The herdr session on the machine that agents run in	`default`
`--max-agents <MAX_AGENTS>`	How many tasks it runs at once	`2`
`--job-slots <JOB_SLOTS>`	Extra slots only tasks from jobs take, on top of –max-agents; 0 for none	`1`
`--burst <BURST>`	How many past –max-agents a critical task may start; 0 for none	`1`
`--tag <TAGS>`	A label a task’s –tag can ask for; repeat for more
`--flock <FLOCK>`	The flock it joins (default: the default flock)
`--description <TEXT>`	One line on what the machine is for, for `machine list --wide`
`--herdr`	Also save it in herdr’s sidebar (runs `herdr machine add`)

pastor machine remove #

Remove a machine from flock.toml; tasks already on it keep their rows

argument	does	default
`<NAME>`	The machine, as flock.toml names it
`--herdr`	Also remove herdr’s saved machine with this label

pastor machine move #

Take a machine out of every flock and put it in this one; tasks already on it stay there

argument	does	default
`<NAME>`	The machine, as flock.toml names it
`<FLOCK>`	The flock it moves to

pastor machine list #

A line about the head, then each machine: host, flock, channel, herdr, agents

argument	does	default
`--flock <FLOCK>`	Only the machines of this flock
`-w, --wide`	Add a DESCRIPTION column, cut to the terminal’s width
`--json`	Print as a JSON object, {head, machines}: the head’s row, then the machines

pastor machine describe #

One machine in full: host, flock, channel, versions, agents, recent errors

argument	does	default
`<NAME>`	The machine, as flock.toml names it
`--json`	Print as a JSON object

pastor machine open #

Open the full herdr UI on a machine

argument	does	default
`<NAME>`	The machine, as flock.toml names it

pastor machine authorized-key #

Print the authorized_keys line that lets a machine’s agents reach this head

argument	does	default
`<NAME>`	The machine, as flock.toml names it
`--key <FILE>`	The public key of the machine’s user: a .pub file, or - for stdin (required)

flock #

Manage the flocks: named groups of machines that tasks and jobs target

pastor flock list #

Every flock: default or not, its machines, live agents, queued tasks

argument	does	default
`-w, --wide`	Add a DESCRIPTION column, cut to the terminal’s width
`--json`	Print as a JSON array

pastor flock add #

Declare a flock; with –default, new tasks and jobs go to it

argument	does	default
`<NAME>`	The new flock’s name
`<MACHINES>`	Machines that join it, each with its max_agents
`--default`	Make it the default flock too
`--description <TEXT>`	One line on what the flock is for, for `flock list --wide`

pastor flock join #

Put a machine in a flock, or change its number there; it stays in its other flocks

argument	does	default
`<FLOCK>`	The flock
`<MACHINE>`	The machine, as flock.toml names it
`--max <N>`	At most this many of the flock’s tasks on the machine (default: its max_agents, or its number there already)

pastor flock leave #

Take a machine out of a flock; out of its last one it is in the default flock

argument	does	default
`<FLOCK>`	The flock
`<MACHINE>`	The machine, as flock.toml names it

pastor flock remove #

Remove a flock; refused while it has machines or queued tasks, or is the default

argument	does	default
`<NAME>`	The flock

pastor flock default #

The flock that new tasks and jobs go to

pastor flock default show #

Print the default flock

pastor flock default set #

Make another flock the default; machines stay in their flocks

argument	does	default
`<NAME>`	The flock that becomes the default

pastor flock edit #

Open flock.toml in $VISUAL or $EDITOR; save it only once it is valid

pastor flock describe #

One flock in full: default or not, its agent, machines, live tasks

argument	does	default
`<NAME>`	The flock
`--json`	Print as a JSON object

tick #

Run one scheduler pass now and report what it did

argument	does	default
`--dry-run`	Run connectors and show what would be created; write nothing
`--job <JOB>`	Only this job, and run it whether or not it is due
`--json`	Print as a JSON array, one entry per job run

job #

Manage jobs (files in ~/.config/pastor/jobs/). With a head elsewhere, a job whose file is here is this machine’s; the rest are the head’s

pastor job list #

Every job file: schedule, enabled, last run, next run, last result. With a head elsewhere, the head’s jobs, then this machine’s

argument	does	default
`-w, --wide`	Add a DESCRIPTION column, cut to the terminal’s width
`--json`	Print as a JSON array; with a head elsewhere, each job says `where` it lives (head or shepherd)

pastor job enable #

Enable a job file

argument	does	default
`<NAME>`	The job: its file name without .toml

pastor job disable #

Disable a job file

argument	does	default
`<NAME>`	The job: its file name without .toml

pastor job run #

Fire a job now, ignoring its schedule and enabled; it starts once a run already going has finished

argument	does	default
`<NAME>`	The job: its file name without .toml

pastor job reload #

Re-read the job files, flock.toml and pastor.toml now instead of at the next tick

pastor job edit #

Open a job file in $VISUAL or $EDITOR; save it only once it is valid

argument	does	default
`<NAME>`	The job: its file name without .toml

pastor job describe #

One job in full: schedule, connector, dispatch, last runs, recent tasks

argument	does	default
`<NAME>`	The job: its file name without .toml
`--json`	Print as a JSON object

orchestrator #

Manage orchestrators (files in ~/.config/pastor/orchestrators/): the head runs a pre script on a schedule and starts an agent with the orchestrator role for what it prints, or keeps one agent running through set hours

pastor orchestrator list #

Every orchestrator file: kind, state, schedule, last and next run, its last agent

argument	does	default
`-w, --wide`	Add a DESCRIPTION column, cut to the terminal’s width
`--json`	Print as a JSON array

pastor orchestrator describe #

One orchestrator in full: its settings, note, last runs with the lines each pre script printed, and recent events

argument	does	default
`<NAME>`	The orchestrator: its file name without .toml
`--json`	Print as a JSON object

pastor orchestrator run #

Run a scheduled orchestrator now, ignoring its schedule and enabled; it starts once a run already going has finished, and is skipped while its last agent works

argument	does	default
`<NAME>`	The orchestrator: its file name without .toml

pastor orchestrator start #

Start a session orchestrator now, inside its hours or not, enabled or not; it stops at the next hours.stop

argument	does	default
`<NAME>`	The orchestrator: its file name without .toml

pastor orchestrator stop #

Stop a session orchestrator: its agent gets a last message and is closed after stop_grace; it does not start on its hours again before they next end

argument	does	default
`<NAME>`	The orchestrator: its file name without .toml

pastor orchestrator enable #

Enable an orchestrator file

argument	does	default
`<NAME>`	The orchestrator: its file name without .toml

pastor orchestrator disable #

Disable an orchestrator file; an agent it started keeps running

argument	does	default
`<NAME>`	The orchestrator: its file name without .toml

pastor orchestrator note #

Keep the orchestrator’s handover note (4 KiB at most), which every agent it starts gets in its prompt; the last one wins, and an empty one removes it

argument	does	default
`<TEXT>`	The note; `-` reads it from stdin
`--name <NAME>`	The orchestrator, for a person; its own agent and scripts may leave it out

config #

pastor.toml: the head’s settings and the task defaults

pastor config edit #

Open pastor.toml in $VISUAL or $EDITOR; save it only once it is valid

argument	does	default
`--local`	This machine’s pastor.toml, even with a head on another machine

completions #

Print a shell completion script (fish, bash, zsh, …) to stdout

argument	does	default
`<SHELL>`	The shell to write the script for (one of `bash`, `elvish`, `fish`, `powershell`, `zsh`)

events #

Show the events log (task, job and machine events)

argument	does	default
`--follow`	Keep printing new events as they are written (reads the file, and works with the daemon down; with a remote head, asks it every second)
`--task <TASK>`	Only events about this task, like t-12 or 12
`--json`	Print one JSON record per line, the same shape hooks get on stdin

watch #

Print one line per change to act on: tasks, failing jobs, the head, connector lines

argument	does	default
`--now`	Print what needs attention now (blocked, done, failed and stale tasks, failing jobs, a head that does not answer, connector lines) and exit
`--name <NAME>`	The watcher’s name: its cursor is kept under the state dir, so a watcher started again with the same name repeats nothing	`default`
`--reset`	Forget the cursor and start from the end of the events log
`--all`	Every task state change, not only blocked, done, failed and stale (with –now: every live task too)
`--json`	Print one JSON record per line: kind, the line’s fields, and line, its text
`--interval <INTERVAL>`	How often to look, like 30s or 2m	`1m`
`--connector <ID>`	Run this connector’s [watch] command (repeatable); replaces [[watch.connector]] in pastor.toml

setup #

Install pastor or herdr as a user service (systemd, or launchd on macOS)

pastor setup systemd #

Install and manage a systemd user unit: pastor.service, or herdr.service with –herdr

With no action flag, the unit is installed and then enabled and started (systemctl --user enable --now). –enable, –start, –enable –start, –enable –now and –stop choose a different systemctl action instead.

argument	does	default
`--herdr`	Install herdr.service (the herdr server) instead, for a flock machine
`--enable`	Enable the unit at login
`--start`	Start the unit now
`--now`	With –enable, start the unit now too (`systemctl --user enable --now`)
`--stop`	Stop the unit now
`-y, --yes`	Skip the confirmation prompt; needed when stdin is not a terminal (a script, a task, `ssh host pastor setup systemd`)

pastor setup launchd #

Install and manage a launchd user agent on macOS: pastor.serve, or pastor.herdr with –herdr

The agent goes to ~/Library/LaunchAgents. With no action flag it is installed, enabled and loaded, which starts it. –enable, –start, –enable –start, –enable –now and –stop choose a different action instead: –enable clears a launchctl disable so it loads at login, and also loads an agent that is not loaded yet, which starts it (launchd cannot register an agent without loading it); –start loads it (or kickstarts it when already loaded), –stop unloads it until the next login.

argument	does	default
`--herdr`	Install pastor.herdr (the herdr server) instead, for a flock machine
`--enable`	Enable the agent at login; one not loaded yet is loaded, which starts it
`--start`	Start the agent now
`--now`	With –enable, start the agent now too
`--stop`	Stop the agent now
`-y, --yes`	Skip the confirmation prompt; needed when stdin is not a terminal (a script, a task, `ssh host pastor setup launchd`)

connector #

Install, link, list and try out connectors

pastor connector install #

Install a connector from GitHub: owner/repo, or owner/repo/subdir

argument	does	default
`<SOURCE>`	owner/repo, or owner/repo/subdir, on GitHub
`--ref <GIT_REF>`	Branch, tag or commit to check out
`--yes`	Do not ask for confirmation

pastor connector link #

Use a connector from a local directory, in place (for developing one)

argument	does	default
`<PATH>`	The connector’s directory, with its pastor-connector.toml

pastor connector uninstall #

Remove an installed connector (its .env and state are kept)

argument	does	default
`<ID>`	The connector’s id, as `connector list` shows it

pastor connector unlink #

Remove a linked connector; the directory itself is left alone

argument	does	default
`<ID>`	The connector’s id, as `connector list` shows it

pastor connector list #

List connectors: version, connector, hooks, missing secrets

argument	does	default
`-w, --wide`	Add a DESCRIPTION column, cut to the terminal’s width
`--json`	Print as a JSON array

pastor connector describe #

One connector in full: manifest, origin, commands, config, secrets, jobs

argument	does	default
`<ID>`	The connector’s id, as `connector list` shows it
`--json`	Print as a JSON object

pastor connector try #

Try a connector: run its command once for a job and print its items; creates no tasks and saves no cursor. watch runs its [watch] command instead and prints its lines

argument	does	default
`<ID>`	The connector’s id, as `connector list` shows it
`<PART>`	`watch`: run the [watch] command `pastor watch` runs (one of `watch`)
`--job <JOB>`	The job whose [connector] config to use; need not exist yet
`--since <SINCE>`	How far back `since` points (default: the job’s backfill, or 0s)

profile #

Permission profiles: named tool allow and deny lists, built in and from pastor.toml

pastor profile list #

Every permission profile: name, where it comes from, what it extends

argument	does	default
`--json`	Print as a JSON array

pastor profile describe #

One profile with its extends followed: the allow and deny lists it adds up to

argument	does	default
`<PROFILE>`	The profile’s name, as `profile list` shows it
`--json`	Print as a JSON object

limit #

The accounts that ran out of usage, which no new task starts on until they reset

pastor limit list #

Every exhausted account: its model, when it is tried again, what ran out, who saw it

argument	does	default
`--json`	Print as a JSON array

pastor limit clear #

Forget an account’s limit, so queued and waiting tasks start on it on the next pass

argument	does	default
`<ACCOUNT>`	The account, as `limit list` shows it: an agent’s `account`, or `<machine>/<agent>`
`--model <MODEL>`	Clear only this model’s limit, not the whole account’s

trust #

The repos whose folder-trust prompt pastor answers on each machine

pastor trust list #

Every saved trust: machine, repo, and when it was saved

argument	does	default
`--json`	Print as a JSON array

pastor trust add #

Save a trust, so the repo’s tasks on that machine are answered

argument	does	default
`<MACHINE>`	The machine, as flock.toml names it
`<REPO>`	The repo’s path on that machine, as `trust list` shows it

pastor trust remove #

Forget a saved trust; the repo’s next task asks again

argument	does	default
`<MACHINE>`	The machine, as flock.toml names it
`<REPO>`	The repo’s path on that machine, as `trust list` shows it

bridge #

Pass request lines from stdin to this machine’s head; for a remote CLI over ssh

argument	does	default
`--agent`	Pass on only what an agent on –machine may ask: its machine’s tasks
`--machine <MACHINE>`	The machine whose agents this bridge serves, as flock.toml names it

head #

Which head this CLI uses: this machine’s, or one on another machine over ssh

pastor head set #

Use the head on another machine, reached over ssh; checked with one ping first

argument	does	default
`<DEST>`	An ssh destination, as ssh takes it (user@host, or a Host alias)
`--pastor <PATH>`	pastor’s path on the head, if it is not on the PATH of a non-interactive shell there
`--force`	Save it even if the head does not answer

pastor head show #

Print the head this CLI uses

argument	does	default
`--json`	Print as a JSON object

pastor head unset #

Use the head on this machine again