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>/role.yaml exists, use it. b. Otherwise scan top-level *.yaml/*.yml for files with apiVersion: initrunner/v1. c. 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.

Full command reference

The full surface area, when you need it.

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

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, Team, Flow) and dispatches accordingly. Mode flags (--daemon, --autopilot, --serve, --bot, --telegram, --discord) 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 spec.agents 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) — 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.

Intent Sensing examples

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

# Search a specific directory for roles
initrunner run --sense --role-dir ./roles/ -p "search the web for AI news"

# Review the sensed role before running
initrunner run --sense --confirm-role -p "review my code for bugs"

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

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 spec.guardrails in the role YAML. See Guardrails.

Team mode

When the role file has kind: Team, the run command executes in team mode — running each persona sequentially or in parallel. A prompt (--task or -p) is required. Interactive (-i) and autonomous (-a) modes are not supported for teams. See Team Mode.

Tool Profiles

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

# Chat with no tools
initrunner run --tool-profile none

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

Extra Tools

Use --tools to add individual tools on top of the selected profile, or use --tool-profile all to enable everything at once.

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

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

Duplicates are ignored — --tool-profile all --tools search won't add search twice.

Run initrunner run --list-tools to see this list from the CLI.

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/ --tool-profile all

# Combine with a bot
initrunner run --telegram --ingest ./knowledge-base/

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.

Provider Auto-Detection

When --provider is not specified, 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 --provider google

# Force both provider and model
initrunner run --provider openai --model gpt-5-mini

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 spec.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

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, flow validate walks every role file referenced by spec.agents and prefixes nested issues with agents.<name>. so you can tell which referenced file broke.

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]

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.