Using Agents with CLI

Use MONOid CLI as an agent interface for auth, task context, and assignment updates

Start your coding agent and ask it to use your installed MONOid CLI.

Give the agent a valid MONOid API token and tell it to run CLI commands with JSON output when possible.

Safe handoff pattern

Give the agent a small, explicit scope:

Goal: Update these MONOid tasks after completing docs work.
Allowed reads: whoami, day, tasks get/list, routine-blocks list.
Allowed writes: tasks update for the task ids listed below.
Do not delete resources.
Before each write: show the current task JSON.
After each write: fetch the same task and confirm the changed fields.
Output: include command summaries and any task ids changed.

Use read-only API keys for discovery. Add write scope only for the phase that changes tasks. Avoid delete scope unless the job explicitly requires deletion.

Agent prompt pattern

export MONOID_API_TOKEN="mo_..."
monoid whoami

Use MONOID_API_TOKEN for agent and CI usage. When stdout is not a TTY, the CLI defaults to JSON output.

If the agent runs commands in a normal terminal, pass -o json explicitly so the output remains parseable.

Useful commands for agent workflows

# Workspace and task context
monoid inbox this_week -o json
monoid week -o json
monoid day -o json
monoid task-nav -o json
monoid categories list --entity-type task -o json
monoid tasks list --category-id <category_id> -o json
monoid tasks list --organisation-id <org_id> --assignee-id <user_id> -o json
monoid tasks list --do-date-gte 2026-04-01 --do-date-lte 2026-04-30 -o json

# Inspect available integrations for assignment
monoid integrations list --organisation-id <org_id> -o json

Write then verify

Every write should have a verification command.

# Inspect current state
monoid tasks get <task_id> --include-notes false -o json

# Make a scoped change
monoid tasks update <task_id> \
  --bucket in_progress \
  -o json

# Verify the same task after the write
monoid tasks get <task_id> --include-notes false -o json

For batch work, list the targets first and verify a representative sample plus any failures:

monoid tasks get <id_1> --include-notes false -o json
monoid tasks update <id_1> --ids <id_1>,<id_2>,<id_3> --bucket done -o json
monoid tasks get <id_1> --include-notes false -o json
monoid tasks get <id_2> --include-notes false -o json

Assigning and scheduling from CLI

Use first-class task flags:

# Assign agent + immediate run mode
monoid tasks update <task_id> \
  --agent-integration-id <integration_id> \
  --agent-dispatch-mode immediate \
  -o json

# Assign agent + routine-triggered mode
monoid tasks update <task_id> \
  --agent-integration-id <integration_id> \
  --agent-dispatch-mode routine_trigger \
  -o json

# Schedule by timestamp (ISO or epoch)
monoid tasks update <task_id> --scheduled-at 2026-05-20T09:00:00Z -o json

# Schedule by routine block
monoid tasks update <task_id> --routine-block-id <routine_block_id> -o json

Verify assignment or scheduling immediately:

monoid tasks get <task_id> --include-notes false -o json

Clear fields explicitly:

monoid tasks update <task_id> --clear-agent-integration -o json
monoid tasks update <task_id> --clear-agent-dispatch-mode -o json
monoid tasks update <task_id> --clear-scheduled-at -o json
monoid tasks update <task_id> --clear-routine-block -o json

Overview — Agent model and providers
Task Assigning — UI assigning flow
CLI Overview — General CLI conventions
Output formats — JSON, table, CSV, and error output