CLI reference - ollim-bot

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.

Command overview

Command	Description
`ollim-bot`	Start the Discord bot
`ollim-bot routine`	Manage recurring routines (cron-based)
`ollim-bot reminder`	Manage one-shot reminders
`ollim-bot tasks`	Manage Google Tasks
`ollim-bot cal`	Manage Google Calendar events
`ollim-bot gmail`	Read and search Gmail
`ollim-bot chat`	Talk to the agent from the terminal, without Discord
`ollim-bot eval`	Run ADHD behavior evals against the real agent
`ollim-bot auth`	Manage Claude Code authentication
`ollim-bot doctor`	Run diagnostic checks on your installation
`ollim-bot help`	Show help message
`counterfactual`	Replay a transcript with an intervention (separate entry point)

`routine`

Manage recurring routines stored as markdown files in ~/.ollim-bot/routines/.

`routine add`

Create a new routine with a cron schedule.

Flag	Type	Required	Default	Description
`--message`, `-m`	string	Yes	—	Agent prompt to execute on each trigger
`--cron`	string	Yes	—	5-field cron expression (minute hour day month weekday)
`--description`, `-d`	string	No	`""`	Short summary shown in `routine list`
`--background`	flag	No	`false`	Run in a background fork instead of the main session

The --cron value must have exactly 5 space-separated fields. The command exits with code 1 if the expression is invalid.

When --background is set, additional options become available. See Background mode options.

`routine list`

List all routines. No arguments.

ollim-bot routine list

Output format:

  abc123  cron '0 9 * * 1-5'              Morning briefing
  def456  [bg] cron '30 8 * * *'          Check inbox

Background routines display tags like [bg], [isolated], the model name, and thinking status.

`routine cancel`

Remove a routine by ID.

Argument	Type	Required	Description
`id`	positional	Yes	Routine ID (shown in `routine list`)

ollim-bot routine cancel abc123

Exits with code 1 if the routine is not found.

`reminder`

Manage one-shot reminders stored as markdown files in ~/.ollim-bot/reminders/.

`reminder add`

Schedule a one-shot reminder that fires after a delay.

Flag	Type	Required	Default	Description
`--message`, `-m`	string	Yes	—	Reminder message
`--delay`	int	Yes	—	Fire in N minutes from now
`--description`, `-d`	string	No	`""`	Short summary shown in `reminder list`
`--foreground`	flag	No	`false`	Run in the foreground instead of a background fork
`--background`	flag	No	—	Deprecated — reminders already default to background. Prints a warning if used.
`--max-chain`	int	No	`0`	Maximum follow-up chain depth

--foreground and --background are mutually exclusive — the command exits with an error if both are set.

Reminders run in the background by default, so background mode options are always available. See Background mode options.

`reminder list`

List all pending reminders. No arguments.

ollim-bot reminder list

Output format:

  xyz789  [fg] at 2026-02-25 14:30                        Take a break
  uvw456  [bg,isolated] at 2026-02-25 15:00 (chain 1/3)   Check email

`reminder cancel`

Remove a reminder by ID.

Argument	Type	Required	Description
`id`	positional	Yes	Reminder ID (shown in `reminder list`)

ollim-bot reminder cancel xyz789

Exits with code 1 if the reminder is not found.

`tasks`

Manage Google Tasks. Requires Google integration setup. Every tasks subcommand accepts --list <id> to target a specific task list. When omitted, the google_task_list runtime config key is used (defaults to @default). See Google Tasks for details.

`tasks list`

List tasks from the configured task list.

Flag	Type	Required	Default	Description
`--all`	flag	No	`false`	Include completed tasks
`--list`	string	No	`google_task_list`	Task list ID to query

ollim-bot tasks list
ollim-bot tasks list --all
ollim-bot tasks list --list MDc3NDk2NzQ3MTE0MTI2NjU5NzU6MDow

Output format:

  abc123  2026-03-01    [ ]  Buy groceries [+]
  def456  (no due)      [ ]  Call dentist

Tasks with notes display a [+] marker after the title.

`tasks show`

Show full details for a specific task — title, status, due date, notes, and ID.

Argument / Flag	Type	Required	Default	Description
`id`	positional	Yes	—	Task ID (shown in `tasks list`)
`--list`	string	No	`google_task_list`	Task list ID

ollim-bot tasks show abc123

Example output:

title:     Buy groceries
status:    needs action
due:       2026-03-01
notes:     Milk, eggs, bread
id:        abc123

`tasks add`

Create a new task.

Argument / Flag	Type	Required	Default	Description
`title`	positional	Yes	—	Task title
`--due`	string	No	—	Due date in `YYYY-MM-DD` format
`--notes`	string	No	—	Task notes
`--list`	string	No	`google_task_list`	Task list ID

ollim-bot tasks add "Fix login bug" --due 2026-02-15
ollim-bot tasks add "Buy groceries" --notes "Milk, eggs, bread"

`tasks done`

Mark a task as completed.

Argument / Flag	Type	Required	Default	Description
`id`	positional	Yes	—	Task ID
`--list`	string	No	`google_task_list`	Task list ID

`tasks update`

Update an existing task. At least one of --title, --due, or --notes is required.

Argument / Flag	Type	Required	Default	Description
`id`	positional	Yes	—	Task ID
`--title`	string	No	—	New title
`--due`	string	No	—	New due date in `YYYY-MM-DD` format
`--notes`	string	No	—	New notes
`--list`	string	No	`google_task_list`	Task list ID

`tasks delete`

Delete a task.

Argument / Flag	Type	Required	Default	Description
`id`	positional	Yes	—	Task ID
`--list`	string	No	`google_task_list`	Task list ID

`cal`

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_calendars runtime 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.

`cal today`

Show today’s calendar events.

Flag	Type	Required	Default	Description
`--calendar`	string	No	All configured	Calendar ID to query

ollim-bot cal today
ollim-bot cal today --calendar work@example.com

When more than one calendar is configured, events are merged and sorted client-side, and each line is tagged with its source calendar ID in brackets.

`cal upcoming`

Show upcoming events.

Flag	Type	Required	Default	Description
`--days`	int	No	`7`	Number of days to look ahead
`--calendar`	string	No	All configured	Calendar ID to query

ollim-bot cal upcoming
ollim-bot cal upcoming --days 14

`cal show`

Show details for a specific event.

Argument / Flag	Type	Required	Default	Description
`id`	positional	Yes	—	Event ID
`--calendar`	string	No	First configured	Calendar ID

`cal add`

Create a calendar event.

Argument / Flag	Type	Required	Default	Description
`summary`	positional	Yes	—	Event title
`--start`	string	Yes	—	Start time in `YYYY-MM-DDTHH:MM` format
`--end`	string	Yes	—	End time in `YYYY-MM-DDTHH:MM` format
`--description`	string	No	—	Event description
`--calendar`	string	No	First configured	Calendar ID to insert into

ollim-bot cal add "Team standup" --start 2026-02-25T09:00 --end 2026-02-25T09:30

`cal update`

Update an existing event. At least one of --summary, --start, --end, or --description is required.

Argument / Flag	Type	Required	Default	Description
`id`	positional	Yes	—	Event ID
`--summary`	string	No	—	New title
`--start`	string	No	—	New start time in `YYYY-MM-DDTHH:MM` format
`--end`	string	No	—	New end time in `YYYY-MM-DDTHH:MM` format
`--description`	string	No	—	New description
`--calendar`	string	No	First configured	Calendar ID

`cal delete`

Delete a calendar event.

Argument / Flag	Type	Required	Default	Description
`id`	positional	Yes	—	Event ID
`--calendar`	string	No	First configured	Calendar ID

`cal calendars`

List every calendar your Google account can access. No arguments.

ollim-bot cal calendars

Output format — one line per calendar, ID first then display name:

  primary                                  My Calendar
  work@example.com                         Work
  family12345@group.calendar.google.com    Family

Use this output to pick IDs for the google_calendars config key or the --calendar flag.

`gmail`

Read and search Gmail messages. Requires Google integration setup. Read-only access — no sending or modifying emails.

`gmail unread`

List unread emails.

Flag	Type	Required	Default	Description
`--max`	int	No	`20`	Maximum number of results

ollim-bot gmail unread
ollim-bot gmail unread --max 5

`gmail read`

Read a specific email by ID. Message bodies longer than 3000 characters are truncated.

Argument	Type	Required	Description
`id`	positional	Yes	Message ID

`gmail search`

Search emails using Gmail query syntax.

Argument / Flag	Type	Required	Default	Description
`query`	positional	Yes	—	Gmail search query
`--max`	int	No	`20`	Maximum number of results

ollim-bot gmail search "from:boss subject:urgent"
ollim-bot gmail search "after:2026/02/01 has:attachment"

`gmail labels`

List all Gmail labels. No arguments.

ollim-bot gmail labels

`chat`

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 chat
ollim-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.

Session behavior

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.

Scope

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

`eval`

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.

`eval run`

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 scenarios
ollim-bot eval run

# Run a single scenario with transcript output
ollim-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.

`eval list`

List available scenarios with their IDs and goals. No arguments.

ollim-bot eval list

`eval results`

Show past eval results from the JSONL history.

Argument	Type	Required	Description
`scenario_id`	positional	No	Filter results by scenario

ollim-bot eval results
ollim-bot eval results overwhelmed-by-tasks

`eval compare`

Compare latest vs previous results for regression detection. Flags a regression when the overall score drops by more than 0.3.

Flag	Type	Required	Default	Description
`--last`	int	No	`2`	Compare last N runs

ollim-bot eval compare

`auth`

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). Start the login flow. Suppresses the browser and prints an auth URL for you to visit manually.

ollim-bot auth login

`auth status`

Show current authentication status. No arguments.

ollim-bot auth status

`auth logout`

Log out from your Anthropic account. No arguments.

ollim-bot auth logout

`doctor`

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: set

DATA DIRECTORY
  PASS  DATA_DIR: /home/user/.ollim-bot
  PASS  DATA_DIR writable: yes
  PASS  DATA_DIR git: initialized

TIMEZONE & SCHEDULING
  PASS  timezone: America/Los_Angeles
  PASS  APScheduler timezone: accepted

ROUTINES
  PASS  routine files: 3 loaded
  PASS  morning-briefing: next fire 9:00 AM (in 2h 30m)

REMINDERS
  PASS  reminders: none pending

TOOL POLICY
  PASS  tool policy: no background items to validate

STATE 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/claude

CLAUDE AUTH
  PASS  Claude auth: logged in

SUMMARY: 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`

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 message
counterfactual prev 418a8812 --append "Respond in one sentence."

# Swap to haiku with a single turn for a cheap smoke test
counterfactual 408bc4a1 418a8812 --model haiku --max-turns 1

# Disallow Bash and compare against a baseline
counterfactual 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.

Background mode options

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.

`--update-main-session` modes

Mode	Behavior
`always`	Fork must report results to main session
`on_ping`	Report only if the fork pings the user (default)
`freely`	Reporting is optional
`blocked`	`report_updates` returns an error — no reporting

The --no-ping flag completely disables ping and embed tools. Even the critical bypass mechanism cannot override it.

Examples

Routines
Reminders
Google Services

# Morning briefing every weekday at 9 AM
ollim-bot routine add --cron "0 9 * * 1-5" -m "Morning briefing"

# Background email check every hour, isolated context
ollim-bot routine add --cron "0 * * * *" -m "Check inbox for urgent emails" \
  --background --isolated --model haiku -d "Hourly inbox check"

# List all routines
ollim-bot routine list

# Cancel a routine
ollim-bot routine cancel abc123

# Remind in 30 minutes
ollim-bot reminder add --delay 30 -m "Take a break"

# Reminder with follow-up chain
ollim-bot reminder add --delay 60 -m "Check build status" \
  --max-chain 3 -d "Build check"

# List pending reminders
ollim-bot reminder list

# Tasks
ollim-bot tasks add "Review PR" --due 2026-02-25
ollim-bot tasks list
ollim-bot tasks show abc123
ollim-bot tasks done abc123

# Calendar
ollim-bot cal today
ollim-bot cal upcoming --days 14
ollim-bot cal add "Focus time" --start 2026-02-25T14:00 --end 2026-02-25T16:00

# Gmail
ollim-bot gmail unread --max 10
ollim-bot gmail search "from:github subject:review"

Next steps

Routines

Learn about the routine file format and cron scheduling.

Reminders

One-shot reminders and follow-up chains.

Background forks

How background mode works under the hood.

Configuration reference

Environment variables and data directory layout.

​Command overview

​routine

​routine add

​routine list

​routine cancel

​reminder

​reminder add

​reminder list

​reminder cancel

​tasks

​tasks list

​tasks show

​tasks add

​tasks done

​tasks update

​tasks delete

​cal

​cal today

​cal upcoming

​cal show

​cal add

​cal update

​cal delete

​cal calendars

​gmail

​gmail unread

​gmail read

​gmail search

​gmail labels

​chat

​Session behavior

​Scope

​eval

​eval run

​eval list

​eval results

​eval compare

​auth

​auth login

​auth status

​auth logout

​doctor

​counterfactual

​Background mode options

​--update-main-session modes

​Examples

​Next steps

Routines

Reminders

Background forks

Configuration reference

Command overview

`routine`

`routine add`

`routine list`

`routine cancel`

`reminder`

`reminder add`

`reminder list`

`reminder cancel`

`tasks`

`tasks list`

`tasks show`

`tasks add`

`tasks done`

`tasks update`

`tasks delete`

`cal`

`cal today`

`cal upcoming`

`cal show`

`cal add`

`cal update`

`cal delete`

`cal calendars`

`gmail`

`gmail unread`

`gmail read`

`gmail search`

`gmail labels`

`chat`

Session behavior

Scope

`eval`

`eval run`

`eval list`

`eval results`

`eval compare`

`auth`

`auth login`

`auth status`

`auth logout`

`doctor`

`counterfactual`

Background mode options

`--update-main-session` modes

Examples

Next steps