DocsInstallCLI ReferenceChangelogCommunityGitHub ↗
Reference

CLI Reference.

The commands you'll use in 2.3.0, with their main flags. Start typing to filter — hit / from anywhere. foreman <command> --help has the rest.

/
79 commands

Setup & lifecycle

foreman initCreate Foreman's home: identity, policy, database and secrets key.
--reset-policyOverwrite policy.yaml with the default template.
--reset-soulOverwrite SOUL.md with the default identity template.
$ foreman init
foreman setupOnboarding wizard: LLM providers, Foreman's model (incl. Ollama), agents and Claude Code's hook, chat services, integrations, install, and your team of roles.
--resumePick up from the last completed step.
--resetClear setup state and start over.
$ foreman setup --resume
foreman startOpen the TUI. Runs the gateway itself, or attaches to the background service when it runs (the header says attached).
--no-onboardingSkip the setup prompt even on a fresh home.
--skip-setupLaunch with the default policy only and remember the choice.
$ foreman start
foreman daemonRun the local daemon without the TUI. Agents' mcp-stdio and the PreToolUse hook connect to it.

No flags.

$ foreman daemon
foreman service installRun the whole gateway in the background at login, so approvals reach your chat with no terminal open (launchd on macOS, systemd user unit on Linux / WSL2). Run it again after upgrading Node or Foreman.

No flags.

$ foreman service install
foreman service statusIs the service installed and running, which process runs the gateway, where it logs.

No flags.

$ foreman service status
foreman service uninstallStop the background service and remove its file.

No flags.

$ foreman service uninstall
foreman demoWatch a company of agents at work in a sandbox: no keys, nothing touched.
--speed <n>Play the scripted day faster (default: 1).
--keepKeep the demo directory afterwards.
$ foreman demo --speed 2
foreman doctorCheck everything: agents, Claude Code's hook, the gateway and where approvals go, channels, MCP. Exit 0 = ok, 1 = warnings, 2 = failures.
--jsonStructured JSON report.
$ foreman doctor --json
foreman completion <shell>Print a shell completion script (bash, zsh, fish).

No flags.

$ foreman completion zsh > ~/.zsh/completions/_foreman
foreman migrate-configMove a legacy ~/.foreman/ install into the platform-native directories.

No flags.

$ foreman migrate-config

Agents

foreman agent add [name]Register an agent, mint its identity token and wire Foreman into its MCP config. With another name and --type, add another Claude Code or Codex instance for another role.
--type <registryId>Registry entry id (defaults to the name when it is one), e.g. codex or claude-code for an instance.
--auto-installInstall the agent when its binary is missing.
--config-path <path>Write the wiring to a non-default config.
--skip-configDon't touch the agent's config.
--token-out <path>Also write the identity token to a 0600 file.
--key-out <path>Write the agent's private key to a 0600 file (it is never printed).
$ foreman agent add backend --type codex
foreman agent hook install <agent>Check Claude Code's built-in tools with Foreman's PreToolUse hook; blocks the call if the hook can't run. Re-run after upgrading. uninstall removes it.
--project [dir]Only this project: <dir>/.claude/settings.json (default: the current folder).
--dry-runShow what would change without writing.
$ foreman agent hook install claude-code
foreman agent listList registered agents, including disabled and blocked ones.

No flags.

$ foreman agent list
foreman agent show <name>Agent detail, public key fingerprint and MCP config snippet.

No flags.

$ foreman agent show codex
foreman agent rewire [name]Give an agent its identity token and rewrite its MCP wiring.
--allRewire every registered agent.
--token-out <path>Also write the token to a 0600 file.
$ foreman agent rewire --all
foreman agent token rotate <name>Mint a new identity token; the old one stops working at once.

No flags.

$ foreman agent token rotate codex
foreman agent remove <name>Unregister an agent, revoke its key and token, and remove Foreman's entry (and hook) from its config.
--yesSkip the confirmation.
$ foreman agent remove hermes --yes
foreman agent block <id>Block an agent on every transport (unblock restores it).

No flags.

$ foreman agent block openclaw
foreman agent disable <id>Pause an agent without removing its config (enable resumes it).

No flags.

$ foreman agent disable hermes

MCP hub

foreman mcp-stdioServe as an MCP server over stdio so an agent routes its calls through Foreman.
-s, --source <id>Agent id; trusted only with that agent's token in FOREMAN_AGENT_TOKEN.
$ foreman mcp-stdio --source my-bot
foreman mcp catalogList the curated MCP servers foreman mcp add knows.

No flags.

$ foreman mcp catalog
foreman mcp add <id> [args...]Add a catalog server or your own (--command / --url) for every agent, mediated.
--command <command>Custom stdio server command.
--url <url>Custom streamable-HTTP server (https://).
--env <KEY=VALUE>Environment; use ${secret:name} for secrets.
--oauthRemote server uses MCP OAuth (then foreman mcp login).
--param <KEY=VALUE>Catalog parameter, e.g. host=gitlab.example.com.
$ foreman mcp add github
foreman mcp tools [name]Connect, list tools, show poisoning-scan findings and token cost.
--refreshIgnore the pinned cache and ask the live servers.
--jsonEmit JSON.
$ foreman mcp tools github
foreman mcp trust <name>Accept a server's current tool definitions (re-pin after an update).
--include-flaggedAlso accept tools the scanner flagged.
$ foreman mcp trust github
foreman mcp login <name>Sign in to a server marked auth: oauth in your browser (logout deletes it).

No flags.

$ foreman mcp login linear
foreman mcp mode <mode>How agents discover hub tools: eager, lazy (fewest tokens) or auto.

No flags.

$ foreman mcp mode lazy
foreman mcp listShow configured servers, their state and OAuth sign-in.

No flags.

$ foreman mcp list

Integrations

foreman integrations catalogGitHub, GitLab, Jira & Confluence, Trello, Linear, Notion and their variants.

No flags.

$ foreman integrations catalog
foreman integrations add <id>Credentials or sign-in, review and pin the tools, then enable for the agents you pick.
--agents <ids>Agents that may use it (comma-separated).
--departments <ids>org.yaml departments whose members may use it.
--read-writeAllow write tools (read-only is the default).
--token-stdinRead the credential from stdin.
--name <name>Server name, e.g. github-work for a second account.
$ foreman integrations add github --agents claude-code,codex
foreman integrations listConfigured integrations and their state.

No flags.

$ foreman integrations list
foreman integrations show <name>Server, credentials, access per agent, tool rules, problems.

No flags.

$ foreman integrations show github
foreman integrations update <name>Change access level, audience, a tool rule, or rotate a credential.
--tool TOOL=RULEPer-tool rule; can only make a tool stricter.
$ foreman integrations update github --tool create_issue=allow
foreman integrations review <name>Connect, scan and pin the tools (needed before enabling).

No flags.

$ foreman integrations review github
foreman integrations enable <name>Enable (refused until credentials, sign-in and review are done); disable cuts agents off at once.

No flags.

$ foreman integrations enable github

Policy, audit & inbox

foreman policy showList the loaded policy rules.
--jsonEvery condition, plus bucket overrides.
$ foreman policy show
foreman policy editOpen policy.yaml in $EDITOR, then load it and report the rule count.

No flags.

$ foreman policy edit
foreman policy resetOverwrite policy.yaml with the default template (asks first).

No flags.

$ foreman policy reset
foreman policy remembered listRules made from your always allow / deny always answers (remove <id> deletes one).

No flags.

$ foreman policy remembered list
foreman log tailShow the most recent requests from the audit log.
-n, --limit <N>Rows to show (default: 20).
-f, --followPoll for new rows every 2 s.
--session <id>One agent-to-agent chain.
--jsonEmit JSON.
$ foreman log tail --follow
foreman log search <query>Full-text (FTS5) search across recent requests.
-n, --limit <N>Max rows (default: 50).
--jsonEmit JSON.
$ foreman log search ".env"
foreman log show <requestId>Full detail and security report for one request.
--jsonEmit JSON.
$ foreman log show 4827
foreman inboxApprovals, blocked calls, crashed agents, updates (read marks all read).
--unreadOnly unread items.
--jsonEmit JSON.
$ foreman inbox --unread

Secrets

foreman secrets add <name>Store a secret in the encrypted store (prompts for the value).

No flags.

$ foreman secrets add github-pat
foreman secrets listList secret names, never values.
--jsonEmit JSON.
$ foreman secrets list
foreman secrets show <name>Print a secret value (requires --reveal; audited).
--revealShow the plaintext.
$ foreman secrets show github-pat --reveal
foreman secrets rotate <name>Replace the value of an existing secret.

No flags.

$ foreman secrets rotate github-pat
foreman secrets remove <name>Remove a secret; says when an integration still uses it.

No flags.

$ foreman secrets remove old-key

Approvals & notifications

foreman notify enable <channel>Turn a channel on (telegram, slack, discord, email, ntfy, webhook, system) and point it at its credentials.
--chat-id <id>Telegram: your chat with the bot.
--channel <name>Slack: the channel; Discord: the channel id.
$ foreman notify enable telegram --chat-id 123456789
foreman notify approval-botA second Telegram bot for approvals, only Foreman holds it. Needed only when a chat agent (Hermes, OpenClaw) reads your main bot.
--offGo back to relaying approvals through the chat bot.
$ foreman notify approval-bot
foreman notify slack-interactiveApprove and run /foreman from Slack (Socket Mode).
--user <id>Slack user id allowed to decide and command (repeatable).
--offBack to push-only Slack (also removes the allowed and owner user ids).
$ foreman notify slack-interactive --user U012ABCDEF
foreman notify discord-interactiveApprove and run /foreman from Discord (Gateway).
--user <id>Discord user id allowed to decide and command (repeatable).
--offBack to push-only Discord (also removes the allowed and owner user ids).
$ foreman notify discord-interactive --user 123456789012345678
foreman notify ntfy-setupPhone push in one step: private ntfy topic, stored, enabled and routed.
--server <url>ntfy server (default: https://ntfy.sh).
$ foreman notify ntfy-setup
foreman notify test <channel>Send a test notification to check a channel's credentials.

No flags.

$ foreman notify test telegram
foreman notify route <level> [channels...]Choose which channels receive a level (critical, warning, info, …).

No flags.

$ foreman notify route critical telegram ntfy
foreman notify silence <duration>Mute non-critical notifications for a window; critical alerts still fire.

No flags.

$ foreman notify silence 2h

Foreman Org: your company of agents

foreman org templatesStarter org charts: startup, software-team, solo.

No flags.

$ foreman org templates
foreman org initCreate org.yaml (departments, roles, reporting lines) from a template.
--template <id>startup | software-team | solo (default: startup).
--company <name>Company name.
--forceReplace an existing org.yaml.
$ foreman org init --template software-team --company "Acme"
foreman org showShow the org chart, with which agents are registered and each role's tools.
--jsonOutput JSON.
$ foreman org show
foreman org validateCheck org.yaml: structure, cycles, unknown managers, unregistered agents.

No flags.

$ foreman org validate
foreman org add-department <id>Add a department and its head role.
--head <role>Role id of the head (created if missing).
--agent <agent>Agent that fills a new head role.
--name <name>Display name.
--title <title>The head's title.
--reports-to <role>Who the head reports to (default: you).
$ foreman org add-department marketing --head cmo --agent claude-code --name Marketing
foreman org rolesThe role library: manager, developer, code-reviewer, researcher, writer, analyst, support, assistant.

No flags.

$ foreman org roles
foreman org add-role <id>Add a role: a ready-made one (--preset) or your own (--describe), filled by an agent you registered or a new instance.
--preset <id>Start from a ready-made role (see foreman org roles).
--describe <text>What the role does, in your own words; the agent is told this.
--agent <agent>An agent you registered fills the role.
--runs-on <type>A new instance of claude-code or codex, named after the role, fills it.
--can <list>What its agent may do: read, write, shell, network (comma-separated).
--department <id>Department it belongs to.
--reports-to <role>Manager role (default: the department head, else you).
--title <title>Job title.
--responsibility <text>What the role is for, in one line.
--model <model>A cheaper model for routine work.
$ foreman org add-role code-reviewer --preset code-reviewer --department engineering
foreman org check <from> <to>Explain whether <from> may hand work to <to> (policy.yaml first, then the chart).

No flags.

$ foreman org check engineer cmo
foreman org assign <target> <task...>Give a task to a role, a department (its head) or an agent.

No flags.

$ foreman org assign marketing "draft the launch post"
foreman org messages [channel]Read what your agents say to each other: all channels, or one department, role, leadership or all.
--followKeep printing new messages.
--limit <n>How many (default: 30).
$ foreman org messages engineering --follow
foreman org tell <target> <message...>Post as yourself to a department, role, leadership or all-hands.

No flags.

$ foreman org tell all "welcome to launch week"
foreman org channel <target> [platform] [channel]Mirror a team channel to Slack or Discord (off removes it).

No flags.

$ foreman org channel marketing slack "#marketing"
foreman org escalate [on|off]Let a manager agent recommend on its reports' low- and medium-risk approvals. You still decide.

No flags.

$ foreman org escalate on
foreman org report [target] [period]What the company, a department, role or agent did and what it cost (today, week, month, 7d).
--jsonOutput JSON.
$ foreman org report marketing month
foreman org budget <department> [usd]Set a department's spend limit (off removes it); alerts at 80% and 100%.
--dailyA daily limit instead of monthly.
--pauseWhen spent, agents can't hand the department new work (you still can).
--warnWhen spent, only alert (default).
$ foreman org budget marketing 50 --pause
foreman org syncPush each role's title, responsibility and model to the registered agents.

No flags.

$ foreman org sync
foreman usage [period]Agent token spend by department, agent or model.
--by <group>department | agent | model.
--jsonOutput JSON.
$ foreman usage week --by agent
foreman usage env <agent>Make an agent you start yourself report its usage to Foreman.

No flags.

$ foreman usage env claude-code

More

foreman write <agent> <message...>Give an agent a task; the gateway runs it and the result arrives in your chat. From chat: /foreman write.

No flags.

$ foreman write codex "add tests for src/rate-limit.ts"
foreman wrap <command...>Launch a child process under Foreman and audit its MCP-framed calls.
--name <agentId>Agent id recorded on every call.
--restart <mode>never | on-failure.
$ foreman wrap --name my-agent -- my-agent-binary start
foreman llm <subcommand>Optional LLM features (verification, smart reports): status, enable, login, budget, usage.

No flags.

$ foreman llm status
foreman registry listThe curated agent registry (info, validate, update).

No flags.

$ foreman registry list
foreman identity showForeman's persona (SOUL.md): show, edit, reset, push.

No flags.

$ foreman identity show