CLI reference - ollim-bot

The ollim-bot CLI is the single 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]

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

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

`tasks list`

List tasks from your default task list.

Flag	Type	Required	Default	Description
`--all`	flag	No	`false`	Include completed tasks

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

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	Type	Required	Description
`id`	positional	Yes	Task ID (shown in `tasks list`)

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

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	Type	Required	Description
`id`	positional	Yes	Task ID

`tasks update`

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

Argument / Flag	Type	Required	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

`tasks delete`

Delete a task.

Argument	Type	Required	Description
`id`	positional	Yes	Task ID

`cal`

Manage Google Calendar events. Requires Google integration setup. All times use the configured timezone (OLLIM_TIMEZONE, defaults to system local).

`cal today`

Show today’s calendar events. No arguments.

ollim-bot cal today

`cal upcoming`

Show upcoming events.

Flag	Type	Required	Default	Description
`--days`	int	No	`7`	Number of days to look ahead

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

`cal show`

Show details for a specific event.

Argument	Type	Required	Description
`id`	positional	Yes	Event 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

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

`cal delete`

Delete a calendar event.

Argument	Type	Required	Description
`id`	positional	Yes	Event ID

`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

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

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.

Configuration

Development

​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

​gmail

​gmail unread

​gmail read

​gmail search

​gmail labels

​eval

​eval run

​eval list

​eval results

​eval compare

​auth

​auth login

​auth status

​auth logout

​doctor

​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`

`gmail`

`gmail unread`

`gmail read`

`gmail search`

`gmail labels`

`eval`

`eval run`

`eval list`

`eval results`

`eval compare`

`auth`

`auth login`

`auth status`

`auth logout`

`doctor`

Background mode options

`--update-main-session` modes

Examples

Next steps