Skip to content

leo task

Manage scheduled tasks.

Usage

leo task list                 # list configured tasks
leo task list --json          # list configured tasks as JSON
leo task add [flags]          # add a new task — flag-first, falls back to interactive on a TTY
leo task remove <name>        # remove a task from the config (prompts for confirmation)
leo task enable <name>        # enable a task
leo task disable <name>       # disable a task
leo task history [name]       # show execution history (all tasks or one)
leo task logs <name>          # show the latest run's log output

Task names support shell tab-completion for remove, enable, disable, history, and logs.

Subcommands

leo task list

Displays all configured tasks with schedule, model, enabled status, last run result, and the next scheduled run (when the daemon is running):

  NAME                 SCHEDULE           MODEL    STATUS   LAST RUN             NEXT RUN
  heartbeat            0,30 7-22 * * *    sonnet   enabled  Apr 13 08:30 ok      Apr 13 09:00
  daily-briefing       0 7 * * *          opus     enabled  Apr 13 07:00 ok      Apr 14 07:00
  weekly-report        0 9 * * 1          sonnet   disabled

Pass --json for a machine-readable array suitable for piping into jq or scripting.

leo task add

Flag-first: supply all required fields on the command line for a non-interactive add, or run with no flags on a TTY to be prompted for any missing required fields.

Flags:

Flag Description
--name <name> Task name (required for non-interactive add).
--schedule <cron> 5-field cron schedule, e.g. '0 7 * * *' (required for non-interactive add).
--prompt-file <path> Prompt file path relative to the task workspace (required).
--model <model> Claude model override (blank = use defaults.model).
--channels <csv> Comma-separated channel plugin IDs used for notify_on_fail.
--notify-on-fail Spawn a short child claude invocation on non-zero exit to notify configured channels. Requires --channels.
--silent Prepend the silent-mode preamble to the prompt.
--disabled Create the task in a disabled state (default: enabled).

Example — fully non-interactive:

leo task add \
  --name heartbeat \
  --schedule "0,30 7-22 * * *" \
  --prompt-file prompts/heartbeat.md \
  --notify-on-fail \
  --channels plugin:telegram@claude-plugins-official

Or interactively:

leo task add

If the prompt file does not exist yet, Leo prints a warning so you remember to author it before the first scheduled run.

leo task remove <name>

Removes the task from the config. When the daemon is running, the removal is sent over the daemon socket so the scheduler drops the entry without a restart.

Prompts for confirmation by default. Pass -y / --yes to skip the prompt (required when stdin is not a TTY, e.g. scripts).

leo task enable <name> / leo task disable <name>

Toggles the task enabled flag. When the daemon is running, the change is forwarded to the scheduler immediately via the daemon IPC. Otherwise the config is saved and the change is picked up the next time the scheduler reads it.

leo task history [name]

Without a name, shows a one-row-per-task summary of the most recent run:

  TASK                 RUNS  LAST RUN
  heartbeat            412   Apr 13 08:30 ok
  daily-briefing       87    Apr 13 07:00 ok
  weekly-report        12    Apr 12 09:00 FAIL (timeout, exit 124)

With a task name, shows the full history for that task:

History for "daily-briefing" (last 30 runs):

  2026-04-13 07:00:15  ok
  2026-04-12 07:00:09  ok
  2026-04-11 07:00:12  FAIL (non-zero exit, exit 1)

Failures include a typed reason (timeout, non-zero exit, crash) alongside the exit code.

leo task logs <name>

Prints the captured log output from the most recent run of the task.

Flags:

Flag Default Description
-n, --tail 0 Show only the last N lines (0 = show everything).

Logs live under ~/.leo/state/logs/ and are written every time the task runs.

See Also