aura tasks

Manage and run scheduled tasks.

Syntax

aura tasks [--files ...] list
aura tasks [--files ...] show <name>
aura tasks [--files ...] run [names...] [--now] [--concurrency N] [--prepend ...] [--append ...] [--start N] [--timeout D]

Description

Tasks are named sets of commands defined in .aura/config/tasks/*.yaml. Each task has a list of commands (slash commands, prompts, and !-prefixed shell commands) that execute sequentially through the assistant. Tasks can optionally have a cron-like schedule for automatic execution via the daemon.

Common Flags

Flag	Short	Default	Description
`--files`			Additional task file globs to load (repeatable, supports `**` syntax)

External task files are merged with default ones. If a pattern matches no files, it errors. Supports doublestar glob syntax (e.g. /shared/tasks/**/*.yaml).

Subcommands

Subcommand	Description
`list`	List all configured tasks with schedule, status, and timeout
`show <name>`	Display a task’s full definition
`run [names...]`	Run tasks on schedule (default) or immediately (`--now`)

Run Flags

Flag	Default	Description
`--now`	`false`	Run tasks immediately instead of on schedule
`--concurrency`	`1`	Maximum number of tasks to run in parallel
`--prepend`		Commands to insert before the task’s command list (repeatable)
`--append`		Commands to append after the task’s command list (repeatable)
`--start`	`0`	Skip first N commands (or N items for foreach tasks)
`--timeout`	`0`	Override task timeout (0 = use task’s configured timeout)

Root flags --agent and --mode take precedence over task YAML when explicitly set.

Plus all global flags.

Task File Format

Tasks are YAML files in .aura/config/tasks/. Each file is a map of task names to definitions:

daily-review:
  description: Summarize yesterday's git activity
  schedule: "cron: 0 9 * * 1-5"
  timeout: 5m
  agent: high
  mode: Ask
  pre:
    - git pull --rebase
  commands:
    - >
      Review git commits from the last 24 hours.
      Summarize changes and flag potential issues.
  post:
    - echo "Review complete"

reindex:
  schedule: "daily: 02:00"
  timeout: 10m
  agent: high
  tools:
    enabled: ["Query"]
  commands:
    - "/query"

Fields

Field	Type	Default	Description
`inherit`	list	`[]`	Inherit from parent task(s). Key absent = inherit, key present = replace
`description`	string	`""`	Human-readable summary
`schedule`	string	`""`	Schedule expression (see below). Empty = manual-only
`timeout`	duration	`5m`	Max wall-clock time per execution
`agent`	string	`""`	Agent to activate before running commands
`mode`	string	`""`	Mode to activate before running commands
`session`	string	`""`	Session name to resume (see Session Continuity below)
`workdir`	string	`""`	Working directory for task execution. Overridden by `--workdir` flag
`disabled`	bool	`false`	Skip this task without removing its definition
`tools`	object	`{}`	Tool filter with `enabled`/`disabled` glob patterns (see below)
`features`	object	`{}`	Feature overrides merged on top of the agent’s effective features (see below)
`vars`	map	`nil`	Task-scoped template variables (see Task-Scoped Variables below)
`env`	map	`nil`	Task-scoped environment variables (see Environment below)
`env_file`	[]string	`[]`	Dotenv files to load (paths relative to config home)
`pre`	[]string	`[]`	Shell commands to run before the assistant (see Pre/Post Hooks below)
`commands`	[]string	required	Command sequence: prompts, `/slash` commands, or `!shell` commands
`foreach`	object	`nil`	Iteration source — `file:` or `shell:` (see Foreach below)
`finally`	[]string	`[]`	Commands to run once after the foreach loop (requires `foreach`)
`on_max_steps`	[]string	`[]`	Shell commands to run when the assistant hits its step limit
`post`	[]string	`[]`	Shell commands to run after the assistant (see Pre/Post Hooks below)

Template Expansion

Task files use two delimiter systems:

Load-time {{ }} — expanded before YAML parsing. Sprig functions, environment variables, and --set variables. Used for structural templates ({{- range }}, {{- if }}).
Runtime $[[ ]] — expanded per-command at execution time. Converted to {{ }} after YAML parsing. Used for iteration variables (.Item, .Index) and execution context (.Workdir, .Date).

cleanup:
  commands:
    - 'Delete files older than {{ env "RETENTION_DAYS" | default "30" }} days'
    - 'Working in $[[ .Workdir ]]'

Schedule Syntax

Prefix	Example	Description
`cron:`	`cron: 0 9 * * 1-5`	Standard 5-field crontab
`every:`	`every: 30m`	Fixed interval (Go duration)
`daily:`	`daily: 09:00,17:00`	Every day at specified times
`weekly:`	`weekly: mon,wed,fri 09:00`	Specific weekdays + time
`monthly:`	`monthly: 1,15 09:00`	Specific days of month + time
`once:`	`once: 2026-03-01T09:00:00Z`	Single future execution (RFC3339)
`once:`	`once: startup`	Run once immediately when daemon starts

Session Continuity

Tasks with a session: field resume a named session before executing commands and auto-save after. This lets the LLM accumulate context across runs — each execution builds on the previous one.

weekly-review:
  schedule: "weekly: mon 09:00"
  session: "weekly-review"
  commands:
    - "Review this week's changes, building on previous findings."

On the first run, the session is created automatically with the given name. Subsequent runs resume it. Without session:, each execution starts with a fresh conversation (existing behavior).

Tool Filtering

Tasks can restrict which tools are available using the same enabled/disabled glob patterns as agents and modes. The filtering chain is: AllTools → agent → mode → task — each level can only further restrict, never expand.

read-only-review:
  agent: high
  tools:
    disabled:
      - Bash
      - Patch
      - Mkdir
  commands:
    - "Review the codebase for potential issues"

mcp-only:
  tools:
    enabled:
      - mcp__myserver__*
      - Read
      - Glob
  commands:
    - "Use the MCP tools to gather data"

enabled: patterns to include (empty = all tools from agent+mode)
disabled: patterns to exclude (takes precedence over enabled)
Supports * wildcards (e.g. mcp__*, Todo*)
The task filter persists through mode switches and config reloads during execution

Feature Overrides

Tasks can override feature settings (compaction thresholds, tool limits, etc.) via a features: block. Task feature values are merged on top of the agent’s already-merged features using non-zero-wins semantics — only fields you set take effect, omitted fields inherit from the agent (which in turn inherits from global defaults).

Override chain: global features → CLI flags → agent frontmatter → mode frontmatter → task definition

heavy-refactor:
  agent: high
  features:
    tools:
      max_steps: 200
    compaction:
      threshold: 90
  commands:
    - "Refactor the auth module"

Available feature keys match features/*.yaml: compaction, title, thinking, vision, embeddings, tools, stt, tts, sandbox, subagent, plugins, mcp, estimation, guardrail. See Features for all fields.

Environment

Tasks can define scoped environment variables via env: and env_file:. These are available in shell commands (pre/post/hooks), LLM tool execution (Bash tool, sandboxed exec, tool hooks), and as runtime template variables.

deploy:
  env:
    API_KEY: "sk-xxx"
    OUTPUT_DIR: "$[[ .Workdir ]]/output"
  env_file:
    - secrets.env
  commands:
    - "Deploy using the API key"

Precedence: env: > env_file: > process env.

Inheritance: Absent env: = inherit parent’s env. Present (even empty {}) = full replace.

Values support runtime templates ($[[ .Workdir ]] etc.) but cannot reference other env vars.

Foreach

Tasks can iterate over lines from a file or shell command output. Each iteration expands runtime template variables in commands: before execution. Use /new in the command list to clear context between iterations.

logs:
  description: Analyze logs of all containers
  timeout: 1h
  agent: logs
  pre:
    - aura tools --mcp-servers portainer mcp__portainer__containers "{}" --raw --headless > /tmp/containers
  foreach:
    file: /tmp/containers
  commands:
    - /new
    - |
      Call mcp__portainer__logs with: { "container": "$[[ base .Item ]]", "environment": "$[[ dir .Item ]]" }
      Analyze the logs and report critical issues.
  finally:
    - |
      Read all findings and summarize the most critical issues.

Foreach Sources

Field	Description
`file:`	Read lines from a file (one item per line, empty lines filtered)
`shell:`	Run a command and read lines from stdout
`continue_on_error:`	When `true`, log per-item errors and continue to the next item instead of aborting
`retries:`	Additional attempts per failed item (0 = no retry). Each retry re-runs `on_max_steps` if applicable

Only one of file: or shell: can be set.

When continue_on_error: true is set, per-item errors are logged and the loop continues to the next item. finally: still runs after the loop. A summary error is returned after all items complete.

Template Variables

Task files use two delimiter systems for template variables:

Load-time {{ }} — structural templates, env vars, --set vars, sprig on static data
Runtime $[[ ]] — per-command variables, expanded at execution time

Variable	Delimiter	Scope	Description	Example
`.Workdir`	`$[[ ]]`	All sections	Effective working directory	`/home/user/project`
`.LaunchDir`	`$[[ ]]`	All sections	Directory where aura was invoked	`/home/user`
`.Date`	`$[[ ]]`	All sections	Trigger time (filesystem-friendly)	`2026-03-06-14-30`
`.Item`	`$[[ ]]`	Foreach only	Current line content	`env1/container1`
`.Index`	`$[[ ]]`	Foreach only	Zero-based iteration index	`0`, `1`, `2`
`.Total`	`$[[ ]]`	Foreach only	Total number of items	`3`

Task-Scoped Variables

Tasks can define their own template variables via vars:. These are available in both load-time and runtime templates:

challenge:
  agent: high
  vars:
    EXPORT_DIR: ../.resources/challenge/logs
    MODEL: gpt-oss:20b
  commands:
    - /export $[[ .EXPORT_DIR ]]/start.log
    - "What model are you? You should be $[[ .MODEL ]]"

Task vars act as defaults — --set flags override them:

# Uses task default MODEL=gpt-oss:20b
aura tasks run challenge

# Overrides MODEL for this run
aura --set MODEL=qwen3:14b tasks run challenge

Task vars participate in inheritance: parent task vars are inherited, child task vars override.

All sprig functions are available in runtime templates — dir, base, split, trimSuffix, env, etc. Runtime variables are expanded in pre:, commands:, post:, foreach: sources, finally:, and on_max_steps: sections.

Two-Delimiter System

Task files use {{ }} for load-time and $[[ ]] for runtime to avoid conflicts:

Load time: {{ env "VAR" }}, sprig functions, and Go template directives ({{- range }}, {{- if }}) are expanded when the YAML file is loaded. These generate YAML structure.
Runtime: $[[ .Item ]], $[[ base .Item ]], $[[ .Workdir ]] etc. pass through load-time expansion as opaque text. After YAML parsing, $[[ is replaced with {{ and ]] with }} so the runtime template engine sees standard Go templates.

This separation means sprig functions on runtime variables work naturally inside structural templates:

batch-process:
  foreach:
    shell: "find . -name '*.go'"
  commands:
    {{- range until 3 }}
    - "Attempt {{ . }}: process $[[ base .Item ]] in $[[ dir .Item ]]"
    {{- end }}

$[[ ]] was chosen over [[ ]] to avoid collision with bash [[ ]] conditional syntax in !-prefixed shell commands.

Structural Templates

Task files support Go template control flow ({{- range }}, {{- if }}) to generate YAML structure:

retry-task:
  commands:
    - "Try creating the file"
    {{- range until 5 }}
    - /assert not exists:/tmp/output.txt "Retry: create the file"
    {{- end }}

Structural templates are expanded before YAML parsing. Runtime $[[ ]] variables inside structural blocks pass through untouched.

Finally

finally: commands run once after all foreach iterations complete. They execute through the assistant like regular commands (not shell hooks). Use them for summarization or aggregation across all items. Requires foreach: to be set.

Shell Commands in Commands

Prefix a command entry with ! to run it as a shell command instead of sending it to the LLM. Shell commands execute via mvdan/sh (same as pre/post hooks). Errors abort the task.

deploy:
  commands:
    - "!git pull --rebase"
    - "Review the changes and summarize"
    - "!echo $[[ .Workdir ]]"
    - |
      !
      echo "running multi-line script"
      ls -la

Single-line: "!git pull" — strips !, runs git pull
Multiline: ! alone on first line, script body below
Template expansion applies before shell execution
Errors abort the task (same as pre hooks). Use !cmd || true to suppress.
Shell output goes to stdout/stderr directly — not visible to the LLM. For LLM-visible output, use the Bash tool via a prompt instead.

Pre/Post Hooks

Tasks can run shell commands before and after the assistant commands. Hooks execute via mvdan/sh (same interpreter as the Bash tool) with direct stdout/stderr output. No sandboxing, no LLM involvement.

deploy-review:
  pre:
    - git pull --rebase
    - mkdir -p /tmp/reports
  commands:
    - "Review changes and write a summary to /tmp/reports/deploy.md"
  post:
    - cat /tmp/reports/deploy.md
    - rm -rf /tmp/reports

Pre hooks run sequentially before session/agent/mode setup. If any hook fails (non-zero exit), the task aborts — commands: and post: are skipped.
Post hooks run sequentially after all commands complete. Failures are reported but commands already ran.
Both inherit the process environment and working directory.
The task’s timeout: covers the entire execution including hooks.

Concurrency

Task execution prevents overload with two layers:

Global limit: --concurrency N caps total parallel executions (default 1 = sequential)
Per-task singleton (scheduler mode): If a task is still running when its next trigger fires, the trigger is skipped (not queued)

Examples

# List all tasks
aura tasks list

# Show task details
aura tasks show daily-review

# Start the scheduler for all scheduled tasks
aura tasks run

# Start the scheduler for specific tasks
aura tasks run daily-review reindex

# Start with parallel execution
aura tasks run --concurrency 3

# Run all scheduled tasks immediately and exit
aura tasks run --now

# Run specific tasks immediately
aura tasks run --now daily-review reindex

# Run a single task with command overrides
aura tasks run --now daily-review --prepend "/mode Ask"