CLI Reference

Five commands you'll actually use

Most days, this is the whole CLI. Everything below exists for when you need it.

• initrunner new: create a new agent role via conversational builder
• initrunner run: run an agent from a YAML file, starter name, or ephemeral mode
• initrunner setup: guided setup wizard for first-time configuration
• initrunner doctor: check provider configuration, API keys, and connectivity
• initrunner install: install a role from InitHub or an OCI registry

Path Resolution

All commands that accept a role path also accept a directory or an installed role name. Resolution order:

1. If the path is a file, use it.
2. If the path is a directory: a. If <dir>/agent.yaml exists, use it. b. If <dir>/role.yaml exists, use it. c. Otherwise scan top-level *.yaml/*.yml for a flat or envelope Agent/Team/Flow document. d. Exactly one match is used; zero or multiple matches produce an error.
3. Otherwise, look up the name in the installed role registry (exact key, owner/name, or display name).

This means initrunner run . works from inside an agent directory, and initrunner run code-reviewer works after initrunner install alice/code-reviewer.

Since v2026.8.9, run adds one step at 2d: when every top-level match is an Agent, the directory is a group and all of them run in one process. Every other command still wants a single file.

Full command reference

The full surface area, when you need it.

PATH can be an agent YAML file (agent.yaml, role.yaml, pdf-agent.yaml), a pipeline file, a flow file, a team file, or a directory containing one. See Path Resolution.

No-subcommand behavior

Running initrunner with no subcommand in a TTY shows an action menu:

  1. Chat
  2. Try a starter
  3. Create an agent
  4. Dashboard (web UI)    # only if dashboard extras are installed

What would you like to do? [1/2/3/4] (1):

• Chat starts an ephemeral REPL using the provider from ~/.initrunner/run.yaml. It attaches the minimal tool profile (datetime, web_reader) unless you pass --tools all, --tools none, or a list of tool types. Enter selects Chat.
• Try a starter lists Agent starters that are ready with your current extras and env (no Team/Flow until you pass -p).
• Create an agent enters the interactive agent builder (initrunner new).
• Dashboard launches the web UI at http://localhost:8100. Last in the list, never the default.

If no provider is configured, a "Setup Required" panel is shown instead.

In non-TTY contexts (piped input), the help text is printed.

initrunner setup no longer asks to open the dashboard. -y and non-TTY print Chat / memory / new.

Global Options

Environment Variables

Run Options

Synopsis: initrunner run [PATH] [OPTIONS]

The PATH argument is optional. Running with no PATH starts an ephemeral REPL (see Quickstart). When --sense is used, PATH is also optional. The run command auto-detects the YAML kind (Agent, Group, Team, Flow) and dispatches accordingly. --daemon and --serve are mutually exclusive.

Since v2026.4.10, run performs pre-flight YAML schema validation before any skill resolution, model resolution, or API call. Errors render as a Rich panel with per-field paths, 1-based line/column numbers, and inline fix suggestions. flow up, flow install, and flow validate additionally walk every role referenced by agents.<name>.use and prefix nested issues with agents.<name>. so you can tell which referenced file is broken.

In interactive terminals, run also prompts for a missing provider API key inline on first use and persists it to ~/.initrunner/.env (mode 0600), with no initrunner setup round-trip required. Non-interactive sessions (CI, piped stdin, redirected stdout) keep the original API key not found error and exit code 1.

Breaking in v2026.8.11: run went from 43 flags to 22. Twenty-one flags were removed because each one duplicated a role YAML field, an environment variable, or another flag. See Flags removed in v2026.8.11 for the full mapping. For this release only, passing a removed flag prints its replacement and exits 2.

Serve options

These two stayed when the other deployment flags went, because they are not agent behavior: the same role binds to loopback on a laptop and to 0.0.0.0 in a container, and moving host into the role would mean keeping a copy of otherwise identical YAML per environment.

Bearer-token auth for --serve comes from INITRUNNER_API_KEY. Binding a non-loopback host without one generates a key and prints it once rather than serving unauthenticated. CORS origins come from security.server.cors_origins in the role.

Ephemeral mode options

These apply only when there is no role file. Passing them alongside one is an error.

Flags removed in v2026.8.11

Each of these had a YAML field, an environment variable, or another flag that already did the job. Passing one prints the replacement and exits 2; that pointer goes away in the next release.

--audit-db, --skill-dir, and --provider were removed from run only. They still exist on the commands where they are not duplicating a role field, such as initrunner audit, initrunner cost, initrunner a2a serve, and initrunner new.

Flags that used to be accepted and silently dropped are now errors that name the flag: --no-memory with a role file, --var and --format in ephemeral mode, --model on Team and Flow targets, --dry-run on a Flow, --host/--port without --serve, and the single-run flags (-i, --resume, --attach, --report, --var, --format, --dry-run, -p) under --daemon or --serve. The last one mattered: --dry-run --daemon used to start the daemon and call the real model.

Intent Sensing examples

# Let initrunner pick the best role for your task
initrunner run --sense -p "analyze this CSV and summarize"

# --sense already searches ./, ./examples/roles, ~/.initrunner/roles and the starters
initrunner run --sense -p "search the web for AI news"

# The sensed role is confirmed automatically whenever there is a terminal
initrunner run --sense -p "review my code for bugs"

# Dry-run: discover + score roles without any LLM calls
initrunner run --sense --dry-run -p "task description"

# Sense within a group: scores its members, not the roles on disk
initrunner run desk.yaml --sense -p "write the customer reply"

Intent Sensing uses a two-pass strategy:

1. Keyword/tag scoring — zero API calls. Selects confidently when one role clearly matches.
2. LLM tiebreaker — compact call used only when the top two candidates are too close. Skipped when --dry-run is set.

Set INITRUNNER_DEFAULT_MODEL to override the model used for the LLM tiebreaker (default: openai:gpt-4o-mini).

See Intent Sensing for the full algorithm reference, role tagging guide, and troubleshooting.

Combine flags: initrunner run role.yaml -p "Hello!" -i sends a prompt then continues interactively.

Note: Token budgets (max_tokens_per_run, autonomous_token_budget, etc.) are set in guardrails in the agent YAML. See Guardrails.

Running one agent from a group

A group, meaning a group file or a directory holding several agent files, lists agents that deploy together but run independently, so run needs to know which one you mean. Since v2026.8.6:

initrunner run desk.yaml                        # lists the members, exits 1
initrunner run desk.yaml --agent intake -p "…"  # runs that member
initrunner run desk.yaml --agent intake -i      # every single-agent flag works
initrunner run desk.yaml --serve                # serves all members, one model ID each
initrunner run desk.yaml --daemon               # one trigger runner per member
initrunner run agents/ --agent intake -p "…"    # same, for a directory of agents

A member picked this way behaves exactly as if you had run its own file, plus whatever the group shares. Flags that steer a single run (-i, -a, --attach, --report, --resume, --var) need --agent.

Team mode

When the file is a team document (agents + run), the run command executes in team mode — running each agent sequentially or in parallel. A prompt (-p) is required. Interactive (-i) and autonomous (-a) modes are not supported for teams. Since v2026.8.6 those flags error instead of being silently ignored, as they already did for flows. See Team Mode.

Tool Profiles

Tool profiles control which tools are available in ephemeral and bot modes.

# Chat with no tools
initrunner run --tools none

# Chat with every available tool
SLACK_WEBHOOK_URL="https://hooks.slack.com/..." initrunner run --tools all

Extra Tools

--tools takes profile names and tool types in the same list, so you can start from a profile and add to it. Values are repeatable or comma-separated.

# Add slack to the default minimal profile
SLACK_WEBHOOK_URL="https://hooks.slack.com/..." initrunner run --tools minimal,slack

# Add multiple tools
initrunner run --tools git --tools shell

Duplicates are ignored, so --tools all,search will not add search twice.

Run initrunner run --help to see this list from the CLI; it is in the help text for --tools.

If a tool requires an environment variable that isn't set, the command exits immediately with an actionable error:

Error: Tool 'slack' requires SLACK_WEBHOOK_URL.
  Export it or add it to your .env file:
  export SLACK_WEBHOOK_URL=your-value

Document Search (--ingest)

The --ingest flag gives you CLI-driven RAG with no YAML file. Point it at a directory and InitRunner chunks, embeds, and indexes the files, then registers search_documents() as a tool.

# Search your docs folder
initrunner run --ingest ./docs/

# Combine with tools
initrunner run --ingest ./docs/ --tools all

How it works:

1. InitRunner resolves the path and globs for supported files.
2. Files are chunked (paragraph strategy, 512 chars, 50 overlap).
3. Chunks are embedded using the auto-detected provider.
4. The search_documents() tool is registered for the session.

Supported file types: .txt, .md, .rst, .csv, .json, .html. Install initrunner[ingest] for .pdf, .docx, and .xlsx.

Each --ingest invocation re-indexes the directory. Vectors are stored in a session-scoped database under ~/.initrunner/stores/.

Memory in Ephemeral Mode

Ephemeral mode has memory enabled by default. The agent remembers facts across turns within a session and can persist them across sessions.

initrunner run                # memory on (default)
initrunner run --resume       # resume last session
initrunner run --no-memory    # disable memory entirely

When memory is enabled, ephemeral mode creates a lightweight memory store with semantic memory. The agent can use remember() and recall() to store and retrieve facts. --resume loads the most recent session for the auto-detected provider. --no-memory disables all memory — each conversation starts fresh.

Memory being on by default means a bare initrunner run needs the vector extra. On a core install or the :slim image, v2026.8.10 and later stop at load with the install line and the --no-memory hint rather than a traceback.

Provider Auto-Detection

With no provider set, InitRunner checks environment variables in this order:

The first key found wins. Ollama is used as a fallback only when no API keys are set and Ollama is running locally.

# Force a specific provider
initrunner run --model google:gemini-3.7-flash

# Or pin the provider once, in ~/.initrunner/run.yaml
initrunner run --model openai:gpt-5-mini

--provider was removed from run in v2026.8.11. Name the provider in --model as provider:model, or set provider: in ~/.initrunner/run.yaml to change what auto-detection settles on.

Environment variables can also be set in ~/.initrunner/.env or a .env file in the current directory. Running initrunner setup writes the provider key there automatically.

Ephemeral Mode Security

• Tool profiles control agent capabilities. The none profile is safest for untrusted environments. The minimal default gives time and web reading. The all profile enables every tool including python, shell, and slack.
• all profile includes python and shell = full host access. Both tools can execute arbitrary code on the host. Never use all in public-facing bots without access control.
• --tools shell grants shell access. Like python, the shell tool allows arbitrary command execution. Only use it in trusted, local contexts.
• --tools slack sends messages to a real channel. The Slack webhook URL is a secret — treat it like a token.
• Bot tokens are secrets. Store them in environment variables or .env files. Never commit tokens to version control.
• Ephemeral bots respond to everyone. Bot mode does not set allowed_users or allowed_roles by default.
• Daily token budget is a cost firewall. Bot mode defaults to 200,000 tokens/day. For production, tune daemon_daily_token_budget in your role's guardrails.
• Use role.yaml for production bots. Ephemeral run shortcuts are for prototyping and personal use. Production bots should use a role file with explicit access control, token budgets, and tool configuration.

New Options

Synopsis: initrunner new [DESCRIPTION] [OPTIONS]

Create a new agent role via conversational builder. Seed modes are mutually exclusive.

Without any seed, starts an interactive conversation where the LLM asks what to build.

Examples

# Generate from description with interactive refinement
initrunner new "a code review bot that reads git diffs"

# Start from a template, skip refinement
initrunner new --template rag --no-refine

# Load from an example
initrunner new --from hello-world

# Blank template with specific provider
initrunner new --blank --provider anthropic

# Import a LangChain agent
initrunner new --langchain my_agent.py

# Fully interactive (no seed)
initrunner new

Tool New Options

Synopsis: initrunner tool new "<description>" [OPTIONS]

Since v2026.6.9, tool new LLM-scaffolds a type: custom tool module plus a pytest stub from a natural-language description. The generated source is AST-validated and is never imported during scaffolding; on a validation failure it retries once. Generated functions default to async def, take config and secrets through an injected tool_config dict, and avoid sandbox-blocked imports. It prints a paste-ready tools: snippet. See the live authoring loop in Custom Tools.

Examples

# Scaffold a custom tool from a description
initrunner tool new "convert between common measurement units"

# Name the module explicitly and pick a provider
initrunner tool new "look up a stock quote" -o quotes.py --provider anthropic

Setup Options

See Setup Wizard for templates, non-interactive usage, and troubleshooting.

Configure Options

Synopsis: initrunner configure <PATH> [OPTIONS]

Switch the LLM provider and model for a role without editing YAML. In interactive mode (no flags), shows available providers and a model picker. In non-interactive mode, pass --provider and/or --model directly. For installed roles, overrides are stored in registry.json and survive hub updates and reinstalls — the installed YAML stays pristine.

Examples

# Interactive — pick provider and model from menus
initrunner configure role.yaml

# Non-interactive — set provider and model directly
initrunner configure role.yaml --provider anthropic --model claude-sonnet-4-6

# Configure an installed role by name
initrunner configure code-reviewer --provider groq

# Revert to the original provider/model
initrunner configure code-reviewer --reset

Post-install adaptation: After initrunner install, if the role requires an API key you don't have, the CLI offers one-step adaptation to a configured provider. Pass --yes to auto-adapt non-interactively.

Serve Options

The serve subcommand was removed. Use initrunner run <PATH> --serve instead. See Run Options for the full flag list and API Server for endpoint details, streaming, multi-turn conversations, and usage examples.

Validate Options

Synopsis: initrunner validate <PATH> [OPTIONS]

Since v2026.4.10, initrunner validate produces the same Rich panel as the run pre-flight — severity labels, per-field paths, 1-based line/column for syntax errors, and inline fix hints. The success-table path is unchanged. For flows and groups, validate walks every role file referenced by agents.<name>.use and prefixes nested issues with agents.<name>. so you can tell which referenced file broke.

Plan Options

Synopsis: initrunner plan <PATH> [OPTIONS]

Since v2026.6.9, plan predicts what a role would do without calling the model. It is a static, offline dry-run and supports only kind: Agent. It reports the reachable tools (function-level via builder introspection, with type, source, and initguard policy columns), would-fire policy decisions, applied guardrails, the sandbox that would engage, armed triggers, and a heuristic token and USD cost estimate. It never raises: a tool whose builder fails or opens a connection is reported at type level with a caveat.

The cost figure uses the same heuristic as cost estimate; per-day and per-month numbers appear when the role has scheduled triggers (cron or heartbeat).

Doctor Options

See Doctor for details.

Daemon Options

The daemon subcommand was removed. Use initrunner run <PATH> --daemon instead. See Run Options for the full flag list and Triggers for trigger configuration.

Hub Options

Synopsis: initrunner hub <command> [OPTIONS]

Manage agent packs on InitHub. The top-level login, logout, whoami, and publish commands are preferred; hub subcommands are deprecated but still work.

hub login

initrunner hub login              # opens browser for device code authorization
initrunner hub login --token TEXT  # pass a token directly (CI/headless environments)

Without --token, the CLI generates a one-time device code, opens the browser to approve it, and polls until authorization completes. The resulting token is stored locally for future commands.

hub publish

initrunner hub publish                                # publish from current directory
initrunner hub publish ./my-agent/                    # publish from a path
initrunner hub publish role.yaml --readme README.md   # attach a README

Requires authentication (hub login) with a token that has publish scope.

hub search

initrunner hub search "code review"
initrunner hub search python --tag automation

hub info

initrunner hub info owner/package-name

Flow Subcommands

See Flow for full multi-agent orchestration documentation.

Flow New Options

Synopsis: initrunner flow new <name> [OPTIONS]

Scaffold a new flow project with role files and flow.yaml. Three patterns are available: chain (linear chain), fan-out (dispatcher + parallel workers), and route (intake with sense-based routing).

Flow Events Options

MCP List-Tools Options

Synopsis: initrunner mcp list-tools PATH [OPTIONS]

MCP Serve Options

Synopsis: initrunner mcp serve PATHS... [OPTIONS]

Pass several role files, or one group file whose members each become a tool (since v2026.8.6).

See MCP Gateway for transport details, client configuration, pass-through mode, and usage examples.

A2A Serve Options

Synopsis: initrunner a2a serve PATH [OPTIONS]

Expose an agent as an A2A (Agent-to-Agent) server using Google's open standard for cross-framework agent communication.

Requires the [a2a] install extra: uv pip install initrunner[a2a].

See A2A Server for agent cards, delegate configuration, and a comparison with --serve and mcp serve.

Vault Subcommands

Synopsis: initrunner vault <command> [OPTIONS]

Since v2026.4.15. Manages the local encrypted credential vault at ~/.initrunner/vault.enc (Fernet + scrypt). The credential resolver checks env vars first, then the vault, so existing api_key_env, token_env, and ${VAR} placeholders keep working without changes. Standard-provider keys resolved from the vault are injected into os.environ so SDK clients (OpenAI, Anthropic, Google) can find them.

Requires the [vault] install extra (or [vault-keyring] to cache the passphrase in your OS keyring): uv pip install initrunner[vault].

All commands accept --no-prompt to fail fast in non-interactive use. Pass the passphrase via INITRUNNER_VAULT_PASSPHRASE for CI. The variable is scrubbed from subprocess environments so it cannot leak to child processes.

# One-time setup
initrunner vault init
initrunner vault set OPENAI_API_KEY            # prompts for value
initrunner vault import                        # pull from ~/.initrunner/.env

# Daily use; your existing roles keep working
initrunner run role.yaml -p "hello"

# CI use
INITRUNNER_VAULT_PASSPHRASE=$VAULT_PASS initrunner vault list

Approvals Subcommands

Since v2026.4.17. See Approvals for the full walkthrough.

initrunner pending

Lists unresolved tool-call approvals across every run in the audit database.

initrunner pending

Shows run_id, tool_call_id, tool name, agent name, timestamp, and the first slice of the arguments. Exits 0 with an empty-state message when nothing is pending.

initrunner approve

Synopsis: initrunner approve RUN_ID [OPTIONS]

Resumes a paused run. Every pending call on the run must end up with a decision before the run resumes — anything unresolved by --tool-call-id defaults to denied.

initrunner approve abc123 --all
initrunner approve abc123 --tool-call-id call_01HW9Q
initrunner approve abc123 --all --deny

Export Agent Spec

Synopsis: initrunner export agent-spec PATH

Since v2026.4.17. Exports a role as a PydanticAI Agent Spec, writing <name>.agent-spec.yaml plus a companion .schema.json in the same directory. Fields outside the Agent Spec overlap (triggers, ingest, memory, skills, sinks, autonomy, reasoning, guardrails, security) are dropped with a warning table — export is lossy by design.

initrunner export agent-spec ./greeter/role.yaml

See Agent Spec Import & Export for the field mapping and round-trip guidance.

Audit Verify-Chain Options

Synopsis: initrunner audit verify-chain [OPTIONS]

Since v2026.4.15. Walks the HMAC-signed audit chain and reports any breaks. Exits non-zero on a missing key or a chain break.

See Audit Trail: Tamper-Evident Chain for output fields, exit codes, and key storage.

Audit Security-Events Options

Synopsis: initrunner audit security-events [OPTIONS]

Since v2026.4.16. Queries the security_events audit table and renders the result as a Rich table. Use it to inspect sandboxed tool calls (sandbox.exec) and other security events the runtime logs.

# Every sandboxed tool call, most recent first
initrunner audit security-events --event-type sandbox.exec

# Just one agent's events
initrunner audit security-events --agent code-runner --limit 200

Every sandboxed call emits a sandbox.exec record with backend, argv0, rc, and duration_ms, attributed to the role's agent name. See Runtime Sandbox: Audit.