Look up all CLI subcommands and flags for managing the bot, routines, reminders, and Google services.
The ollim-bot CLI is the primary entry point for running the bot and managing
routines, reminders, Google Tasks, Google Calendar, and Gmail from the terminal.
With no subcommand, it starts the Discord bot. With a subcommand, it runs the
corresponding operation and exits.
ollim-bot [command] [subcommand] [options]
Installing with uv tool install --editable . also installs a separate
counterfactual command for replaying production
transcripts with modified agent settings — it is a sibling entry point, not
an ollim-bot subcommand.
Manage Google Tasks. Requires Google integration setup.Every tasks subcommand accepts --list <id> to target a specific task
list. When omitted, the google_task_listruntime config key
is used (defaults to @default). See
Google Tasks
for details.
Manage Google Calendar events. Requires
Google integration setup.
All times use the configured timezone (OLLIM_TIMEZONE, defaults to system local).Read commands (today, upcoming) query every calendar listed in the
google_calendarsruntime config key
by default. Write commands (add, show, update, delete) target the
first entry of google_calendars. Pass --calendar <id> on any
command to override for that invocation. See
Google Calendar
for details.
Talk to the agent directly from your terminal — no Discord required. Useful
for debugging agent behavior, trying a local Ollama model, or driving the bot
on a machine without a Discord account.
chat requires Claude authentication — run ollim-bot auth login first.
The command exits with code 1 if you’re not logged in and
ANTHROPIC_AUTH_TOKEN is not set.
Flag
Type
Required
Default
Description
--model
string
No
agent default
Model name for this chat (for example opus or an Ollama model like qwen3.5:2b)
ollim-bot chatollim-bot chat --model opus
Type a message at the you> prompt and press Enter. The agent streams its
response to stdout. Tool activity prints as dim [tool] <label> lines, and
any MCP tool that would normally send a Discord embed prints its title as
[embed] <title>. Exit with Ctrl-D (EOF) or Ctrl-C — on exit the SDK
client disconnects so the session transcript is flushed.
chat shares the main session with the Discord bot via
~/.ollim-bot/state/sessions.json. If a session ID is stored there, chat
resumes it; otherwise a new one starts on the first message. When you
switch between chat and Discord, each side picks up the other’s
conversation — see session management
for the underlying mechanism.chat runs with permission_mode="bypassPermissions", so the agent does not
prompt for tool approvals while you’re at the terminal. This applies to the
main session only — background forks spawned
from chat still enforce the configured tool policy and ping budget.
Chat captures what the agent sends through its Discord channel duck type, but
Discord-only UI elements are inert:
Visible — text responses, tool activity labels, and the titles of any
embeds the agent sends
Not interactive — buttons and view components attached to embeds
(for example, the save/report buttons on a fork exit
embed) print no output and cannot be clicked
Not rendered — file attachments from send_file are recorded
internally but not displayed in the terminal
Run ADHD behavior evals that test whether the bot responds appropriately to
users with ADHD. Each eval plays a simulated ADHD user (Haiku-powered proxy)
against the real bot agent, then scores the transcript with an LLM judge.
eval run requires Claude authentication — run ollim-bot auth login first.
Run scenarios against the real agent. Runs all scenarios by default.
Argument / Flag
Type
Required
Default
Description
scenario_id
positional
No
all
Run a specific scenario by ID
-v, --verbose
flag
No
false
Show full transcript during execution
# Run all scenariosollim-bot eval run# Run a single scenario with transcript outputollim-bot eval run overwhelmed-by-tasks --verbose
Each scenario reports per-criterion scores (1-5 scale), an overall score,
and a PASS/FAIL status. A scenario passes when the overall score is at least
3.0 and no individual criterion scores below 2. Results are saved to a JSONL
history file for regression tracking.
Manage Claude Code authentication. ollim-bot uses the Claude CLI bundled with
the Agent SDK for OAuth — you don’t need to install Claude Code separately.At startup, the bot checks auth status automatically. If not logged in, it
extracts an OAuth URL from the bundled CLI and DMs it to you via Discord.
Click the link to sign in — the bot waits until authentication completes,
then continues startup. The auth subcommands below are for manual use
(pre-authenticating before enabling a service, checking status, or logging out).
Run diagnostic checks across every layer of your installation — environment
variables, data directory, timezone, routines, reminders, tool policy, state
files, Claude CLI, and authentication. Each check reports PASS, WARN,
or FAIL with an actionable message so you know exactly what to fix.
ollim-bot doctor
No subcommands or flags. The command loads your .env, runs all checks, prints
results grouped by section, and exits with code 0 if everything passes or
code 1 if any checks fail.Example output:
ENVIRONMENT PASS DISCORD_TOKEN: set PASS OLLIM_USER_NAME: set PASS OLLIM_BOT_NAME: setDATA DIRECTORY PASS DATA_DIR: /home/user/.ollim-bot PASS DATA_DIR writable: yes PASS DATA_DIR git: initializedTIMEZONE & SCHEDULING PASS timezone: America/Los_Angeles PASS APScheduler timezone: acceptedROUTINES PASS routine files: 3 loaded PASS morning-briefing: next fire 9:00 AM (in 2h 30m)REMINDERS PASS reminders: none pendingTOOL POLICY PASS tool policy: no background items to validateSTATE FILES PASS pending_updates.json: valid JSON PASS config.json: not present (will use defaults) PASS ping_budget.json: valid JSON PASS fork_messages.json: valid JSON PASS inquiries.json: not present (will use defaults)CLAUDE CLI PASS Claude CLI: /path/to/claudeCLAUDE AUTH PASS Claude auth: logged inSUMMARY: 19 passed, 0 warnings, 0 failures
Run ollim-bot doctor after initial setup or whenever something feels off.
It catches the most common issues — missing env vars, corrupt state files,
invalid cron expressions — before they surface as confusing runtime errors.
counterfactual is a separate top-level command, not an ollim-bot
subcommand. uv tool install --editable . installs both entry points.
Replay a real production transcript from a chosen point, apply an intervention
(modified system prompt, tool restrictions, model swap, or alternate message),
and print the agent’s new response alongside the original. Use it to evaluate
prompt or configuration changes without waiting for the behavior to recur in
production. See
Counterfactual trajectory testing
for when to reach for this tool.
counterfactual <session> <rewind_uuid> [options]
Argument
Type
Required
Description
session
positional
Yes
Session ID prefix, prev, prev-N, or slug name — matches claude-history conventions
rewind_uuid
positional
Yes
UUID (or UUID prefix) of the user message to rewind to
Flag
Type
Default
Description
--cwd
string
~/.ollim-bot
Working directory used to locate the session’s Claude project
--project
string
—
Direct path to a project directory under ~/.claude/projects/
--append
string
—
Text appended to the system prompt for the variant run
--replace-prompt
string
—
Replace the system prompt entirely (mutually exclusive with --append)
--model
string
—
Model override (for example, haiku, sonnet, opus)
--message
string
—
Send a different user message than the original
--disallow
string
—
Disallow a tool for the variant run; repeat the flag to disallow multiple tools
--max-turns
int
5
Maximum agent turns per run
--max-budget
float
0.50
Maximum cost per run in USD
--with-baseline
flag
false
Also run a baseline (same settings as original) to separate sampling noise from the intervention’s effect — doubles cost
-v, --verbose
flag
false
Show debug logging
The rewind_uuid must belong to a user message — assistant or tool-result
UUIDs are rejected. Prefixes are accepted as long as they resolve to exactly
one user message. The first record in a session cannot be a rewind point —
there is no prior context to fork from.
# Append to the system prompt and replay the last session's messagecounterfactual prev 418a8812 --append "Respond in one sentence."# Swap to haiku with a single turn for a cheap smoke testcounterfactual 408bc4a1 418a8812 --model haiku --max-turns 1# Disallow Bash and compare against a baselinecounterfactual elegant-hopping-seal 418a8812 --disallow Bash --with-baseline
The output shows the original response from the transcript, an optional
baseline (same settings as the original, re-run fresh), and the
variant (with the intervention). Each block includes the response text,
tool calls, turn count, cost, and token usage.
The variant runs with bypassPermissions and the default --cwd is
~/.ollim-bot — tools like Bash, Write, and Edit can modify files
anywhere under that directory. Discord MCP tools (ping_user,
discord_embed) are not connected, so pick rewind points where the
original response did not depend on them, or the comparison will not be
meaningful.
routine add accepts these flags when --background is set. For reminder add,
these options are always available since reminders run in the background by default.
Flag
Type
Default
Description
--model
string
—
Model override for this fork
--no-thinking
flag
false
Disable extended thinking
--isolated
flag
false
Fresh context, no session history
--update-main-session
choice
on_ping
When to report to main session
--no-ping
flag
false
Disable ping_user and discord_embed
The reminder add command also supports --allowed-tools for
restricting which tools the background fork can use, and
--skills for loading skills at fire time.
Both accept one or more space-separated values.
