Every command

Every foreman command, in the order foreman --help lists them, with each subcommand, flag, what it prints and the exit codes that matter. The first table is the short list most owners need. The last section covers the commands the agents and the supervisor run for themselves, which you rarely type. For what the settings and config keys mean, see Settings and switches and foreman.config.json.

Common tasks

What	How
Build and ship one story	/foreman:story S-1
Run, picking up new stories as they come (standby when there are none), two at a time	/foreman:run, or foreman run --workers 2 (starts in the background; --foreground to stay attached)
Keep the factory running after a crash and at each log-in	foreman service install, foreman service uninstall, foreman service status
See what is happening	foreman status
See what the stories cost and how long they took, per day, and how many full-suite check runs each story took, and which agents ran on another model than set	foreman report, foreman report --since 2026-10-01
See the tokens each agent used, per role, per story and over 14 days, with hints on where to save	foreman report --tokens, foreman report --tokens --json
Run the project checks, reusing Foreman’s run of an unchanged tree (a second slot waits on a run in progress)	foreman checks --changed, foreman checks --changed --reuse
Run the quick command of each check where it has one (what the builder runs while building; never reused)	foreman checks --changed --quick
Print Foreman’s record of this tree without running anything	foreman checks --recorded, or foreman checks --changed --recorded
Run the checks without waiting on them	foreman checks --changed --start, then foreman checks --wait <id>
Run every check, whatever its condition (the story session uses it after a failed merge of the base)	foreman checks --all, or foreman checks --all --start then foreman checks --wait <id>
Pause, resume, stop (after the stories in progress, or at once)	foreman pause, foreman resume, foreman stop, foreman stop --now
Skip a story for the rest of the run, or build a skipped one again	foreman slot w1 skip; foreman next S-4 (foreman status lists the skipped stories)
Finish releases that wait on someone, such as a promotion click	foreman release watch (the run does this every 5 minutes)
Answer the questions Foreman left you	foreman decide list, foreman decide list --all, foreman decide answer <item> <option>, foreman decide answer --bundle follow-ups "Create a follow-up story"
Check the setup	foreman doctor
Set up in the browser	foreman setup
Walk through the set-up	foreman setup next, foreman setup steps --json
Run in the cloud, in a container or in GitHub Actions	foreman cloud run, foreman cloud actions init; see Run in the cloud
Add a rule for one agent	foreman traits add tester "Always run the slow suite"
See or undo what Foreman learned	foreman learning list, foreman learning undo L-3, foreman learning scan --dry-run, foreman learning run <key> --dry-run, foreman learning tick
Change a setting, or turn a feature off	foreman settings set workers 2, foreman features off followUps

Every flag

The shape is foreman <command> [args]. foreman --help, or help in place of a command, prints the command list. An unknown command exits 64 and says so; most commands also exit 64 on bad usage, and 1 when they could not do the job. Each command acts on the project around the current folder, the main checkout of the git repo it is in.

Two guards apply everywhere. Inside a Foreman story session (the environment has FOREMAN_RUN=1), the owner’s controls (run, stop, pause, resume, slot, workers, fixed, handback, next, service install|uninstall, settings set|reset, features on|off and the rest) refuse, and a command that writes the owner’s files acts on a scratch repo or plain folder, never on the project the run builds. With the branch state store, a command that reads or writes run state syncs the state branch around itself first; see Run state on a branch.

run

foreman run [N] [--workers W] [--exit-when-idle] [--foreground] [--dry-run] starts the supervisor, the process that picks stories and runs the slots. N is how many new stories to start; with no N it runs until stopped, waiting on standby when there is nothing to build and starting new stories as they come.

• --workers W: how many slots build at once for this run, 1 to slots. Without it the workers setting applies, which foreman workers and the Settings tab can change while it runs.
• --exit-when-idle: stop instead of standing by, printing “Nothing left to build.”.
• --foreground: stay attached, pass Ctrl-C, a kill and a closed terminal on to the supervisor, and return its exit code. By default the supervisor starts detached in its own session, so closing the terminal or the Claude session that ran it does not stop it, with its output appended to .foreman/logs/supervisor.out.
• --dry-run: print what each slot would start and change nothing. It may run beside a live run.
• --service: the service manager’s own program line (the foreground, plus two rules: a running supervisor and the marker foreman stop leaves both exit 0, so the service is not restarted against them). You never type it; foreman service install writes it.

A background start waits up to 5 seconds for the supervisor to write its pid, then prints the pid, the dashboard address and the log file and returns 0. A supervisor that ends before writing its pid is reported with the tail of its log: exit 0 (“The supervisor finished as it started:”) or 1 (“The supervisor stopped as it started:”). One still starting after 5 seconds prints where to look and no pid. A second run while a supervisor runs is refused. A new run clears an old STOP. When the background service is installed, a plain foreman run asks the service manager to start it instead and takes no story or worker count. A supervisor that sees its own plugin code change exits 75 and is started again on the new code with the same arguments and FOREMAN_RESTART=1, so the run carries on. Inside a story session a run is always in the foreground and is leashed to the shell that started it: it ends when that shell ends, or after 5 minutes on standby. See Run, pause, stop.

service

foreman service install|uninstall|status runs the factory as a per-user background service: a launchd agent on macOS, a systemd user unit on Linux. It keeps going after the terminal closes, restarts after a crash and starts again at each log-in.

• install clears the stop marker and starts the service. It refuses while a supervisor runs, when the service label is already installed for another folder, when the project or log path has a control character in it, and on Linux when systemctl --user does not work.
• uninstall stops the service (a run it had going stops now; its stories resume at the next start) and removes it.
• status prints one line: not installed, running, stopped with foreman stop, or not running.

install and uninstall write to your home folder, so they refuse in every story session. foreman stop stops the service until the next foreman run.

init

foreman init detect prints a suggested config and what it found, as one JSON line. foreman init write [--answers] [--force] [--from <file>] [--marketplace <name>] [--no-example] takes a config on stdin, or from --from <file>, and writes foreman.config.json, the plugin setting, the .gitignore entry for the state folder and an example story. With --answers it takes the Set up tab’s “This project” answers instead (name, source, dir, site, jql, check, ci) and makes the same config the page would, so a set-up with no browser writes the same file. --force overwrites an existing config; --marketplace <name> names the marketplace the plugin setting records (default foreman); --no-example skips the example story. The /foreman:init skill drives both; see Install.

doctor

foreman doctor runs every check in Doctor checks and prints one line each, starting ok, warn or FAIL, then the check’s name and, for a warn or FAIL, a dash and the detail. Under each warn and FAIL goes a fix: line with what to do and the Set up tab step that fixes it. It exits 1 when any error-level check failed; warnings alone exit 0. No key value is ever printed.

foreman doctor --end-strays runs no check. It ends the processes that are not this run’s (the ones the stray processes check counts: old supervisors, hook runs and foreman learn or notify runs in temp folders or this project’s folders and over 10 minutes old), prints “Ending <what>: pid a, b.” then “Ended N.” and any “Still running: pid x.”, and exits 1 when some are left, else 0 (“No stray processes.” when there are none). It refuses inside a story session, so a slot never ends another slot’s tests. Any other argument is ignored.

setup

foreman setup [--no-open] [--port N] serves the dashboard on this computer only until Ctrl-C and opens the browser on it; --no-open only prints the address. With no working foreman.config.json the dashboard is in set-up mode and switches to full mode once set-up writes one. --port takes 0 to 65535.

foreman setup steps [--json] [--step <id>] runs the doctor’s checks and prints each step’s status, one line per step. With --step <id> only that step’s own checks run (plus any whose cached result counts against it), and the others keep their cached results. --json prints one line, { steps: [{ ...step, applies, status, results }] }, skipped steps included.

foreman setup next walks the steps that apply, in order, and stops at the first that needs you or is broken: why, its guide, a fix line per failing result and where to read more. It prints “All set: every step is done.” when none is waiting. Results are cached per machine in .foreman/setup-checks.json. The step ids are on The Set up tab.

config

foreman config check validates foreman.config.json and prints one line per problem as <path>: <message>, then any warning: lines (the deprecated top-level keepAwake, a trait file problem), and ok when the file is valid. foreman config show prints the config with Foreman’s and the pack’s defaults filled in, as JSON. The rules are on foreman.config.json.

settings

foreman settings list [--group <run|models|features|learning|release|jira|notify|console>] [--json] prints each setting’s name, value, source (which layer set it) and when it applies. foreman settings get <name> prints the value in effect as JSON. foreman settings set <name> <value> [--team] sets it locally by default (.foreman/settings.json, this computer only); --team edits foreman.config.json for everyone. foreman settings reset <name> [--team] drops the local value, or with --team the file’s. A setting that does not apply to this project (the Jira ones with markdown stories) is hidden and cannot be set. Values are typed as text: true/on/yes and false/off/no for a switch, a comma list or a JSON list for a list, a JSON object for a map. See Settings and the full list on Settings and switches.

features

foreman features on|off <name> [--team] is shorthand for foreman settings set features.<name> true|false. With no arguments it lists the switches, as foreman settings list --group features does.

jira

foreman jira login [--port 8765] [--no-open | --paste] signs in to Jira Cloud with OAuth 2.0. It starts a one-shot server on this computer on the port, opens the Atlassian consent page (or with --no-open prints its address), waits for the callback, swaps the code for tokens, finds the cloud id of stories.site and saves the token file ~/.config/foreman/jira-<site>.json with mode 600. Your Atlassian app’s callback URL must point at this computer on that port with the path /callback. --paste is for a machine with no browser, such as a container: it starts no server and prints the consent address; you approve anywhere, the browser lands on a callback address that does not load, and you paste that whole address back.

foreman jira status prints the site, the account, the token’s expiry and, when stories.jql is set, whether the JQL runs. foreman jira logout deletes the token file. JIRA_CLIENT_ID and JIRA_CLIENT_SECRET come from the environment, then .env.foreman, then the project’s env file. No token, code or secret is printed. Exits 0 on success, 1 on failure, 64 on bad usage. See Stories from Jira.

cloud

Running Foreman away from a laptop; see Run in the cloud.

• foreman cloud run: the container runner. Clones the project, then builds until stopped, with its settings from the environment.
• foreman cloud doctor: is this machine ready for cloud run. The runner checks first, then the project checks for the project here or the runner’s clone; see Cloud doctor.
• foreman cloud tick [--story <id>]: one scheduled job. Builds at most one story, with the state branch synced around it; the supervisor runs with one worker and stops by itself when nothing can start. --story names the story to build.
• foreman cloud sync: pushes the state folder to the state branch. It is the workflow’s last step, so a cancelled job keeps its state.
• foreman cloud actions init [--force]: writes .github/workflows/foreman.yml, never through a symlink. --force overwrites one that exists.

tick, sync and actions init need the run state on a branch (state.store: "branch"), since nothing on a runner outlives its job. run and tick write the project’s key files, so they refuse inside a story session. A STOP seen at the start of a tick becomes a pause once the stories in progress are finished.

keys

Foreman’s keys without editing env files. A value is pasted, never typed on the command line, and never printed. Every subcommand takes --project <path>, resolved against the current folder; FOREMAN_PROJECT_DIR is never read to find the project.

• foreman keys list: every key Foreman knows and the ones the project’s adapters ask for, each as not set, set outside Foreman (in the environment, which Foreman cannot change) or set in a file, masked.
• foreman keys set NAME: reads the value from the terminal without showing it (or from stdin to its end when stdin is not a terminal), checks its shape and writes it to its file, adding the file to .gitignore first when git does not ignore it. Enter ends the value; Ctrl-C cancels with exit 130.
• foreman keys remove NAME.
• foreman keys test NAME: asks the key’s service whether it takes the key.
• foreman keys migrate: moves Foreman’s own keys (the Jira app keys, Resend and the notify settings, the dashboard token, the Gearset token, the Anthropic key and the Claude token) out of the project’s env file, which is linked into every slot where the agents can read it, into .env.foreman, which git ignores and no slot ever gets. It prints names only: moved A, B to .env.foreman, removed C from .env.local: .env.foreman already has it, left D in .env.local: its value cannot be written safely, added .env.foreman to .gitignore, or nothing to move.

Exits 0 on success; 1 on a config error, a key set in the environment, a name that is not a key or looks like a value, a wrong-shaped value, a failed test, or a file that cannot be read, written or ignored; 64 for anything else, including a value given on the command line. Inside a story session every subcommand refuses against the project the run builds. See Files Foreman writes.

claude

foreman claude use-key goes back to the Console API key from the next story, after the platform credits ran out and the run moved to your subscription (the claude.fallback setting). It refuses and changes nothing when no ANTHROPIC_API_KEY is in the environment or in .env.foreman; it reads whether the key is there, never its value. Exits 0 with one line when the sessions use the key again (or already did), 1 with the reason otherwise. See When things go wrong.

story

Internal: every change to a story’s status and notes goes through here, so a build session never edits a story by hand. Each change raises the event a story source acts on (start raises started, block blocked, done shipped, end failed failed); a Jira or Salesforce source comments and moves the issue, the markdown source ignores events.

Subcommand	What it does
story next [--id X] [--strict] [--skip a,b]	Prints the next story to build as one JSON line
story plan	Shows the build order. Useful by hand to see what Foreman would pick
story start <id>	Marks a story in progress. Run again by the same session it changes nothing
story block <id> --reason <text>	Marks a story blocked
story done <id> --note <text>	Marks a story done
story finalize <id> --note <text>	Marks a story done in this checkout, so the story’s own commit carries it (markdown stories with track: "file")
story todo <id> --note <text>	Puts a story back to todo
story summary <id>	Prints where the story’s group summary goes, as JSON
story set <id> --depends-on <ids>	Replaces the story’s depends_on list (comma-separated)
story depend <id> --on <ids> --reason <text>	Adds dependencies at once and tells you with an FYI whose Undo and Keep the supervisor applies. Refuses unless features.autoApplyDependsOn is on
story end <result> [pr] [reason...] [--findings <file>] [--story <id>] [--builder <name>] [--cause story|environment]	Records how the story ended: shipped, ready-to-promote, blocked, failed, halted, deferred, held or empty
story note <id> --kind design --file <plan>	Records the architect’s design on the story itself, as a comment when features.jiraComments (or salesforceComments for Cases) is on. A design already recorded is not recorded again; a changed plan is recorded as a revision. Other kinds exit 64

end ready-to-promote records a release that finishes later (foreman ship exit 9); it needs that park and otherwise counts as failed, exit 1. See Story files and How Foreman picks.

stage

Internal. foreman stage <name> [detail...] tells the command centre which stage the story is in. It never fails the caller: it always exits 0, and writes any problem to stderr.

lock

Internal: exclusive resources, file locks and owner claims, for the agents. The holder is the supervisor’s pid and the slot in FOREMAN_SLOT.

Subcommand	Exit codes
lock held <name>	0 when this slot holds the resource, else 1 with one line why
lock take <name> <id>	0 when taken now or already held by this slot, else 1
lock release <name>	Frees the resource if this slot holds it; 0 either way, never touching another slot’s lock
lock files <id> --plan <file>	Claims every file the plan names, less fileLocks.ignore and the generated paths, and prints one JSON line. 0 when this slot holds them all; 7 when another slot holds one, or one is kept for a higher-priority story that waited for it; 1 for a usage, plan or config error
lock owner-claim <id>	Hands the story to you (“I’ll take it”)

See Slots for resources, file claims and “Taken by you”.

checks

foreman checks [--changed | --all] [--reuse | --quick] [--start] runs the project’s checks (checks in the config) in the current folder, which in a slot is the slot’s worktree, streaming each one’s output. It prints PASS <run> or FAIL <run> per check and exits 1 when any failed.

• No flag: the checks whose when is always.
• --changed: those, plus each check whose when glob matches a file this branch changed against the base, an untracked file or an uncommitted change. When the base cannot be diffed, every check runs.
• --all: every configured check, whatever its when. Not with --changed.
• --reuse: for each chosen check with a record of a real run on this exact tree, prints that record (when, for which story, how long, the last lines of output, PASS or FAIL) instead of running it. A record is matched on the command and the tree, not the folder, so run it from the repo root.
• --quick: runs each check’s quick command where it has one, else its run. A quick run is recorded as quick and never reused; it cannot be combined with --reuse.
• --recorded: prints each check’s record of this exact tree, headed recorded:, and runs nothing. Exit 1 only for a recorded failure. Not with --reuse, --quick, --start or --wait.
• --start: checks the flags and config, starts the run detached in the session environment and prints its id at once, exit 0.
• --wait <id> [--for <seconds>]: polls that run for up to the seconds given (default 90). Finished: prints its saved output byte for byte and exits with its exit code. Its process gone with no result: FAIL, exit 1. Time used up: “still running”, exit 75, so --wait && git commit can never go ahead early.

Every real run is recorded in .foreman/check-runs.jsonl against the tree’s hash. In a story session the checks run in the environment the supervisor gave the session, not the calling shell’s, and only such runs are ever reused. One run per tree: a second process on the same tree waits for the first and prints its record. One full run per worktree: a newer run on a different tree stops an older one in the same slot, which exits 143. See Story sessions.

review

Internal, run by the review-relay agent when a reviewer has engine set in roles.reviewers. foreman review --start --reviewer <name> --prompt <file> --chars <n> checks the reviewer has an engine and its CLI answers, that the prompt file’s length is within 2% of <n>, copies the prompt into the state folder, starts the engine detached and prints its id, exit 0. foreman review --wait <id> [--for <seconds>] polls for up to the seconds given (default 90).

Exit	Meaning
0	A verdict, printed as JSON with engine and model
1	The engine failed, its process is gone with no result, or any refusal: the “unavailable” JSON is printed so the pipeline runs the Claude reviewer instead
75	Still running; wait again

See Agents and traits.

ship

foreman ship --story <id> (also --story=<id>, or FOREMAN_STORY) releases the committed story branch you are on through the project’s ship.steps, one release at a time. The last line printed is one JSON object { ok, code, ...result }; ok is true for codes 0 and 9. foreman ship --preflight says what each step needs and which env names are missing, and changes nothing; a configured rollback is listed last with when: "on failure". The exit codes are a contract the story skill depends on:

Exit	Meaning
0	Shipped
1	Nothing to ship or wrong state: not on a story/ branch, uncommitted changes, a merge in progress, no commits ahead of the base, or a step that threw
2	CI, the Salesforce validation or the project’s checks on the merged code failed. Nothing merged
3	Hosted credentials missing. Nothing merged
4	Migration failed. Nothing merged; HALT written
5	Deploy or smoke failed, or a failure after a point of no return. HALT written
6	The branch conflicts with the base in real code
7	A resource is held by another slot
8	Releases are frozen by HALT
9	Parked: ready to promote, the release finishes later. Nothing halted
10	You must allow metadata deletes (Salesforce). Nothing pushed, nothing halted

Codes 4 and 5, and any failing step marked as halting, write the HALT file, which stops releases until you clear it with foreman fixed. When the new build is live and the project set a rollback, the runner also rolls production back and says so in the HALT reason. A release that stops for a reason you should see (2, 4, 5, 6, 10, or 1 from a step) is also written on the story when features.jiraComments is on. See How a story ships and Release safety.

release

foreman release watch finishes the releases that are ready to promote. Each parked release is checked through its step’s check: a finished one moves its story to Done, a hard failure blocks the story with the reason, one still waiting stays for the next watch. The last line is { ok: true, checked, results: [{ id, step, outcome, detail }] } and the exit code is 0 whatever the parks said. One watch runs at a time; a second prints { ok: true, busy: true }. A config that cannot be read exits 1. The supervisor runs it every 5 minutes, paused or halted too. See Parked releases.

health

foreman health runs the health check of every configured ship step that has one: the hosted database has exactly the base’s migrations, the base’s newest commit is deployed, the live site answers below 500, the watch command reports no problems. foreman health --site runs only the live-site check (the smoke step’s). It prints one JSON line { ok, reason, checks: [{ step, ok, reason }] } and exits 0 when every check passes, 1 otherwise; with nothing to check it passes with “no health checks are configured”. This is what “I’ve fixed it” runs before clearing a halt.

notify

Internal. foreman notify --kind <kind> [--slot wN] [--parked-for crash|dirty|owner] [--story <id>] [--reason <text>] [--stories n] [--shipped n] [--log file] sends one notification through the project’s notifier. The kinds are halted, stopped, blocked, failed, noresult, parked, down, paused, config, credits, standby, owner-task, unexpected-stop and stuck. It prints Emailed <to>: <subject> or Wrote <file> (the outbox) and exits 1 with one line when nothing was sent. With features.notifications off it writes to the outbox only. See Notifications.

status

foreman status [--json] prints what the run is doing from the same snapshot the dashboard gets: the run line (running, paused, stopped and by whom, stuck, or on the last good config), the workers and each slot’s story and stage, the skipped stories, queued work, stories waiting on a running story’s files, a Learning: N active, M in evaluation line once Foreman has learned anything, and the Waiting on you block as the tab groups it (Needs you now, Your tasks, Quick decisions with the foreman decide command that answers each bundle, Later, FYI). --json prints the snapshot as is. See The dashboard and Waiting on you.

report

foreman report [--since YYYY-MM-DD] [--tokens] [--json] prints what the story sessions cost and how long they took, per day (UTC, by when the session ended) and per result, from the run records in .foreman/runs/. After the totals come a Watchdog section when the watchdog stopped any session, a Learning section (the learner’s calls and spend, and the learned changes added, kept, rolled back, retired and undone), a Checks section per story (full-suite runs and their minutes, quick runs, reuses, waits on another slot’s run, build rounds and hand runs the guard denied), a Models section for agents that ran on another model than their role is set to, and the Tokens section. --tokens prints the tokens each agent role used instead: today, 7 days, this run and the last 14 days per role, a line per story and hints on where to save. --json prints the summary, or with --tokens the token view. See Costs and reports.

dashboard

foreman dashboard [--port N] [--host H] serves the local dashboard in the foreground until Ctrl-C, for watching without a run; foreman run starts the same server itself when console.adapter is dashboard. Host and port default to console.host and console.port. It prints the address, never the token. On a host other than loopback every request needs the token in FOREMAN_DASHBOARD_TOKEN. A port in use, or a project with no config, exits 1 with a line saying so; a bad --port or --host exits 64.

pause

foreman pause starts no new stories until foreman resume; the stories in progress carry on and each slot waits when it finishes. Prints one line.

resume

foreman resume starts stories again after a pause. A pause Foreman made itself (a usage limit, an empty balance) also ends at its reset time by itself; resume starts it sooner.

stop

foreman stop asks the run to finish the stories in progress, then stop, and records who ran it. foreman stop --now writes the same STOP and the service’s stop marker first, then sends SIGTERM to the supervisor whose pid the pid file vouches for; the stories in progress are cut off and resume by priority at the next start. A stale pid, or one another program now holds, signals nothing. See Run, pause, stop.

slot

foreman slot <wN> <action> acts on one slot, w1 to w<slots>. The actions are skip, takeover, park, unpark, resume, restart, resume-as-is and discard; which apply depends on the slot’s state, and the dashboard shows only those. The supervisor applies the request at its next tick.

Action	What it does	When it applies
skip	Stops the story and leaves it out for the rest of this run, standby included; the branch is kept and foreman next brings it back	Building, or parked after a crash
takeover	Commits and pushes the work so far to the story branch, claims the story for you and blocks it; the slot moves on	Building, held, or parked after a crash
park	Parks the slot now; it picks up no stories until you unpark it	Building, idle or down
unpark	Lets the slot pick up stories again	Parked by you
resume	Carries the story on from where it stopped, keeping what was done	Held, down, or parked after a crash
restart	Resets the folder, deletes the local branch and builds the story again from the base	Parked after a crash
resume-as-is	Keeps the uncommitted changes in the folder: with a story they are its work and it carries on; with none they go into a git stash and the slot takes a new story	Parked dirty
discard	Hard resets the folder to the base; the changes are gone for good	Parked dirty

“Park once its current story is done” exists only on the dashboard. See Slots.

workers

foreman workers <n> sets how many slots build at once, 1 to slots, saved for this computer as the workers setting and applied at the next pick. A slot above the new count finishes its story first.

fixed

foreman fixed says the cause of a halt is fixed. The run runs foreman health, and clears the HALT file when it passes. See When things go wrong.

handback

foreman handback <id> gives a story you took back (with takeover or “I’ll take it”) to the factory, so it can be picked again.

next

foreman next <id> asks for that story to be built next, in the next free slot, if it can be built now. It also brings back a story that was skipped this run.

decide

What waits on you, through the project’s console. foreman decide list [--all] prints the open items grouped as the Waiting on you tab groups them (Needs you now, Quick decisions with the command that answers each bundle whole, FYI, then Answered but not yet applied), or with --all every item flat. foreman decide answer <item> <option-or-text> [--note <t>] answers one item; foreman decide answer --bundle follow-ups|traits <option> answers every unanswered item in the bundle with the option. The agents’ side is internal: decide add --story <id> --kind decision|task --title <t> [--option <o>]... [--urgent] [--body <text>] [--summary <t>] [--hint <h>]... [--recommend <option>] [--purpose <t> --happened <t> [--damage <t>] --recommendation <t>] prints the new item’s id, decide pending prints the items not yet applied as JSON with their answers, and decide applied <item> marks one applied. See Waiting on you.

learn

foreman learn [--dry-run] [--min-stories N] turns findings that keep stopping stories into proposed traits, and the minor findings a shipped story left behind into a proposed follow-up story, asking you about each through the console. A rule becomes a proposal once it has been seen on --min-stories different stories (default 3). --dry-run prints a “Would ask:” line per proposal instead. While learning.auto is on (the default) Foreman writes learned traits itself, so learn proposes only follow-ups; with features.autoCreateFollowUps on it creates each follow-up at once (priority Low where the source has priorities) and tells you in one FYI with an Undo. The supervisor runs it after each shipped story and at stop.

• learn apply <decision id>: adds the trait, after “Add as a trait”, or creates the follow-up story, after “Create a follow-up story”.
• learn ignore <decision id>: never propose it again.
• learn reopen <decision id>: takes an ignored proposal back, so the next learn asks again.
• learn undo <decision id>: closes the follow-up stories Foreman created itself, after “Undo and close them” (only those still todo that no live claim holds; the rest are left and said).

Its ledger is .foreman/learn.json. See How Foreman learns.

learning

What Foreman learned by itself (traits and learned skills), with its history and your undo.

• learning list: one line per item: id (L-1, L-2…), kind, roles, version, status, path, reason.
• learning show <id>: the item’s ledger lines, then the text in force.
• learning undo <id> [--told-at <time>]: goes back one version; the first version’s undo removes the item. It applies from the next story a slot starts.
• learning keep <id> [--told-at <time>]: keeps the version in force. --told-at is how the dashboard’s Keep is applied; it refuses when the note is not about the item’s latest change by Foreman.
• learning scan [--dry-run]: the lessons in the last 60 stories, written to .foreman/lessons.json unless --dry-run.
• learning run <key> [--dry-run]: asks the learner session about one lesson from the scan, checks its proposal and prints it; records the call’s cost in .foreman/learner.jsonl unless --dry-run. It never writes a learned item.
• learning tick: what the supervisor runs after each run record, and foreman cloud tick at the end of a job. It evaluates the items on trial (rolls back one that made stories worse, retires one with no effect, keeps one that worked), then scans and, for each new lesson, runs the learner and writes the trait or skill itself, telling you with an FYI whose “Undo the change” and “Keep the change” you answer. It stops at learning.maxEvaluating, learning.maxPerDay or the daily spend cap learning.maxUsdPerDay; with learning.auto off it writes nothing. It refuses in a story session, and exits 1 when it changed something but could not tell you.

See How Foreman learns.

workflow-args

Internal. foreman workflow-args <id> [--plan <file>] [--start-at fix --findings <file>] prints the args the pipeline workflow takes, as one line of JSON, with the config read fresh (so a rounds change applies to the next story), the traits including learned ones unless learning.apply is off, and each role’s learned skills the slot holds. With --plan, filesHeld says whether this slot holds every file the plan claims. After a session stopped without a result it carries the checkpoint’s plan and resume, so the pipeline skips the stages already approved. foreman workflow-args <id> --save-plan saves the architect’s plan from the session’s transcript to .foreman/plans/ and prints the JSON file’s path; exit 1 when the slot has no ready plan. Warnings go to stderr.

traits

foreman traits add <role> <text...> appends a paragraph to .claude/foreman/traits/<role>.md. The role is all or a role named in the config (architect, tester, a builder’s name, a reviewer’s name); an unknown role exits 1 and lists the known ones. See Agents and traits.

sf

foreman sf holds the Salesforce pack’s own commands: sf skills, sf deletes allow|keep-out <id>, sf baseline [--refresh|--story], sf rollback <id> and sf fixed <stage>. It exits 0 on success, 1 on a failure or a config that is not a Salesforce one, 64 on usage, and its last line is always JSON. Each is described on foreman sf. The Salesforce pack is a preview: its release paths pass their own tests, but no story has yet shipped through them on a live org, and the Gearset path has not run against a live Gearset pipeline.

Internal commands

These commands exist for the agents, the story session and the supervisor. They are listed above for completeness; you rarely type them, and the ones that write the owner’s files refuse in a story session against the project the run builds.

Command	Who runs it	When you might
foreman story <sub>	The story session, at each status change; the supervisor for end after a crash	foreman story plan to see the build order; foreman story note <id> --kind design --file <plan> to put a design on a story by hand
foreman stage <name>	The story session, as each pipeline stage starts	Never needed
foreman lock ...	The architect and builder, to claim resources and files; the dashboard’s “I’ll take it” for owner-claim	foreman lock files <id> --plan <file> before a by-hand build, so workflow-args sees the files held
foreman workflow-args <id>	The story skill, to start the pipeline	--save-plan to keep an architect’s plan the session lost
foreman notify --kind <k>	The supervisor, when the run stops, a story blocks or fails, a slot parks or goes down, or the factory pauses	Never needed
foreman decide add, pending, applied	The story skill adds questions and applies answers	list and answer are yours; see above
foreman review --start, --wait	The review-relay agent, for a reviewer with an engine	Never needed; a missing engine falls back to the Claude reviewer