Chat

Zero-config chat, role-based chat, and one-command bot launching. For the full CLI reference, see CLI Reference.

Prerequisites

• InitRunner installed (pip install initrunner or uv tool install initrunner)
• An API key for any supported provider (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.) or Ollama running locally
• For bot mode: the platform optional dependency (pip install initrunner[telegram] or pip install initrunner[discord])

Zero-Config Chat

The fastest way to start chatting. InitRunner auto-detects your API provider and launches a REPL.

Just run initrunner

With no arguments in a terminal, InitRunner picks the right action automatically:

# Auto-detect provider, start chatting
initrunner

Explicit chat subcommand

# Same as bare `initrunner` but explicit
initrunner chat

Send a prompt then continue interactively

# Send a question, then stay in the REPL for follow-ups
initrunner chat -p "Explain Python decorators"

Override provider and model

# Use a specific provider and model
initrunner chat --provider anthropic --model claude-sonnet-4-5-20250929

Role-Based Chat

Load an existing role file with tools, memory, guardrails, and everything else defined in YAML:

initrunner chat role.yaml

When a role file is provided, the --provider, --model, --tool-profile, and --tools flags are ignored — the role file controls everything.

Combine with -p to send an initial prompt then continue interactively:

initrunner chat role.yaml -p "Summarize today's news"

One-Command Bot Mode

Launch a Telegram or Discord bot with a single command:

# Telegram bot
export TELEGRAM_BOT_TOKEN="your-token"
initrunner chat --telegram

# Discord bot
export DISCORD_BOT_TOKEN="your-token"
initrunner chat --discord

Or, to persist tokens across sessions, add them to ~/.initrunner/.env:

TELEGRAM_BOT_TOKEN=your-token
DISCORD_BOT_TOKEN=your-token

Combine with tool flags to give the bot more capabilities:

# Telegram bot with every tool enabled
initrunner chat --telegram --tool-profile all

# Discord bot with just git and shell tools
initrunner chat --discord --tools git --tools shell

What it creates

Bot mode builds an ephemeral role in memory with:

• Name: telegram-bot or discord-bot
• Provider and model: auto-detected from environment
• Tools: minimal profile (datetime + web_reader) by default
• Daily token budget: 200,000
• Autonomous mode: enabled (responds to messages without confirmation)

chat --telegram vs daemon role.yaml

Recommendation: Use chat --telegram / --discord for quick testing. Switch to a role.yaml with initrunner daemon for anything shared or long-running.

CLI Options

Synopsis: initrunner chat [role.yaml] [OPTIONS]

Tool Profiles

Tool profiles control which tools are available in auto-detect and bot modes. When a role file is provided, it defines its own tools and the profile is ignored.

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

# Chat with every available tool
SLACK_WEBHOOK_URL="https://hooks.slack.com/..." initrunner chat --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. This is how you enable outbound integrations (like Slack) without writing a full role.yaml.

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

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

# Combine with a profile
initrunner chat --tool-profile all --tools slack

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

Supported extra tools

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

Fail-fast behavior

If a tool requires an environment variable that isn't set, the command exits immediately with an actionable error. This applies to both --tools and --tool-profile all:

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

Role-file mode

When a role file is provided (initrunner chat role.yaml --tools slack), the --tools flag is ignored with an info message. The role file defines its own tools.

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 chat --ingest ./docs/

# Combine with tools
initrunner chat --ingest ./docs/ --tool-profile all

# Combine with a bot
initrunner chat --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

All core formats are supported: .txt, .md, .rst, .csv, .json, .html. Install initrunner[ingest] for .pdf, .docx, and .xlsx.

Re-indexing

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

Memory in Chat

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

# Default — memory on
initrunner chat

# Resume the last session
initrunner chat --resume

# Disable memory entirely
initrunner chat --no-memory

Default behavior

When memory is enabled (the default), chat 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 chat session for the auto-detected provider. Picks up the conversation where you left off, including any stored memories.

--no-memory

Disables all memory for the session. No facts are stored, no sessions are persisted. 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.

To override auto-detection:

# Force a specific provider (uses its default model)
initrunner chat --provider google

# Force both provider and model
initrunner chat --provider openai --model gpt-4o

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.

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. Anyone with the URL can post to the channel.
• Bot tokens are secrets. Store them in environment variables or .env files. Never commit tokens to version control. Anyone with the token can impersonate the bot.
• Ephemeral bots respond to everyone. Bot mode does not set allowed_users or allowed_roles by default. Every user who can message the bot can use it — and invoke its tools.
• 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 to match expected usage and budget.
• Use role.yaml for production bots. The chat shortcuts are designed for prototyping and personal use. Production bots should use a role file with explicit access control, token budgets, and tool configuration.

Troubleshooting

No API key found

Error: No API key found. Run initrunner setup or set an API key environment variable.

No provider was detected. Either export an API key or start Ollama locally:

export ANTHROPIC_API_KEY="sk-..."
# or
ollama serve

You can also add the key to ~/.initrunner/.env so it persists across sessions:

ANTHROPIC_API_KEY=sk-...

Unknown tool profile

Error: Unknown tool profile 'foo'. Use: none, minimal, all

The --tool-profile value must be one of none, minimal, or all.

Unknown tool type

Error: Unknown tool type 'foo'.
  Supported: datetime, filesystem, git, python, search, shell, slack, web_reader

The --tools value must be one of the supported extra tool types. Run initrunner chat --list-tools to see the full list.

Missing required environment variable for tool

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

Some tools require environment variables. Set the variable before running the command.

--telegram and --discord are mutually exclusive

Error: --telegram and --discord are mutually exclusive.

You can only launch one bot platform at a time. To run both, use two separate role files with initrunner daemon.

TELEGRAM_BOT_TOKEN / DISCORD_BOT_TOKEN not set

Error: TELEGRAM_BOT_TOKEN not set. Export it or add it to your .env file:
  export TELEGRAM_BOT_TOKEN=your-bot-token

Export the token or add it to ~/.initrunner/.env:

export TELEGRAM_BOT_TOKEN="your-token-here"

Or add it to ~/.initrunner/.env:

TELEGRAM_BOT_TOKEN=your-token-here

Module not found (telegram / discord)

Error: python-telegram-bot is not installed.
  Install it: pip install initrunner[telegram]

Install the platform's optional dependency:

# For Telegram
pip install initrunner[telegram]
# or
uv sync --extra telegram

# For Discord
pip install initrunner[discord]
# or
uv sync --extra discord

Wrong provider auto-detected

Auto-detection uses the priority order listed above. If you have multiple API keys set and the wrong provider is picked, override explicitly:

initrunner chat --provider anthropic

What's Next

• CLI Reference — Full command and flag reference
• Discord — Full Discord bot setup with role file and access control
• Telegram — Full Telegram bot setup with role file and access control
• Guardrails — Token budgets, timeouts, and request limits
• Triggers — Cron, file watcher, webhook, and messaging triggers
• Providers — Detailed provider setup and options