aura tasks

Manage and run scheduled tasks.

The task’s agent and mode are selected before session startup. Explicit root --agent, --mode, --model, and --provider flags take precedence over the task selection, for scheduled and immediate runs and when resuming a named task session. Task defaults do not change which CLI flags count as explicitly set. Later /agent switches and failover use the newly selected agent’s own model/provider instead.

Syntax

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. Use aura show tasks to list and inspect tasks.

Flags

Flag	Default	Description
`--files`		Additional task file globs to load (repeatable, `**` supported)
`--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
`description`	string	`""`	Human-readable summary
`schedule`	string	`""`	Schedule expression. 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
`workdir`	string	`""`	Working directory for task execution
`disabled`	bool	`false`	Skip this task without removing its definition
`tools`	object	`{}`	Tool filter with `enabled`/`disabled` glob patterns
`features`	object	`{}`	Feature overrides merged on top of the agent’s effective features
`vars`	map	`nil`	Task-scoped template variables
`env`	map	`nil`	Task-scoped environment variables
`env_file`	[]string	`[]`	Dotenv files to load (relative to config home)
`inherit`	list	`[]`	Inherit from parent task(s)
`pre`	[]string	`[]`	Shell commands to run before the assistant
`commands`	[]string	required	Command sequence: prompts, `/slash` commands, or `!shell` commands
`post`	[]string	`[]`	Shell cleanup after execution, including failure, timeout and handled cancellation
`post_timeout`	duration	`30s`	Independent total time budget for post hooks; must be positive
`foreach`	object	`nil`	Iteration source — `file:` or `shell:`
`finally`	[]string	`[]`	Commands to run once after the foreach loop (requires `foreach`)
`on_max_steps`	[]string	`[]`	Shell commands executed when a turn exhausts its `max_steps` budget, after its final text-only response. Runs outside the LLM loop — useful for sending alerts or cleanup.

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 when daemon starts

Template Variables

Task files support two delimiter systems:

Load-time {{ }} — expanded before YAML parsing. Sprig functions, env vars, --set variables, and control flow.
Runtime $[[ ]] — expanded per-command at execution time. Used for iteration variables and execution context.

Variable	Scope	Description
`.Workdir`	All	Effective working directory
`.LaunchDir`	All	Directory where aura was invoked
`.Date`	All	Trigger time (filesystem-friendly)
`.Item`	Foreach only	Current line content
`.Index`	Foreach only	Zero-based iteration index
`.Total`	Foreach only	Total number of items

Tasks also expose the shared prompt context: .Model.Name, .Provider.Name, .Provider.URL, .Agent, .Mode.Name, .WorkDir, and the other structured fields. Model and provider metadata are available before inference, including explicit CLI selection. Runtime expressions are evaluated immediately before each command or hook phase, so a preceding /model or /agent change is visible to subsequent commands and to post. Task env: values are resolved once during setup.

Shared field names are reserved. Custom task variables and expanded task environment remain available by their existing top-level keys and through .Vars (for example .Vars.Model if a custom key collides with .Model). Use shellQuote when inserting a runtime value as a literal shell argument; it uses the same shell library as task execution. Ordinary ${VAR} expansion continues to use process/task environment, without implicit model variables.

$[[ ]] avoids collision with bash [[ ]] syntax in !-prefixed shell commands.

Task-scoped variables via vars: are available in both template systems. --set flags override them:

challenge:
  vars:
    MODEL: gpt-oss:20b
  commands:
    - "What model are you? You should be $[[ .MODEL ]]"

aura --set MODEL=qwen3:14b tasks run challenge

Session Continuity

Tasks with a session: field resume a named session before executing and auto-save after. Without session:, each run starts fresh.

Tool Filtering

Tasks restrict tools using enabled/disabled glob patterns. 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"

Feature Overrides

Feature override chain: global → agent → mode → task → explicit CLI overrides.

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

Available feature keys: compaction, title, thinking, vision, embeddings, tools, stt, tts, sandbox, subagent, plugins, mcp, estimation, guardrail. See Features.

features.tools.bindings supplies fixed tool arguments and hides them from the model’s input schema. Bindings support runtime $[[ ]] expressions, resolved once per task run after env resolution and before pre/foreach. The same values apply to every iteration; .Item is not available at this stage. Use ordinary YAML booleans/numbers for typed inputs, and strings for text or template values. See Fixed Tool Arguments for enforcement and inheritance.

Environment

deploy:
  env:
    OUTPUT_DIR: "/tmp/output"
  env_file:
    - secrets.env
  commands:
    - "Deploy to the target environment"

Precedence: env: > env_file: > process env.

Shell Commands

Prefix a command entry with ! to run it as a shell command instead of sending it to the LLM. Multiline scripts: put ! alone on the first line, script body below. Errors abort the task; use || true to suppress. Shell output goes directly to stdout/stderr — not visible to the LLM.

Pre/Post Hooks

pre: runs after session/agent/mode and task environment setup, before the task commands; a pre failure aborts the commands. Once setup has completed, post: runs exactly once when execution exits, including a pre failure, an item failure, task timeout, or handled cancellation. It runs after finally: when that section is reached. Configuration/setup failures before hook registration do not run cleanup.

Post hooks use a fresh cancellation-independent context, bounded by post_timeout (30 seconds by default). One failed post command does not prevent the remaining post commands from running within that total deadline. Cleanup errors are reported alongside the original task error rather than replacing it. SIGKILL, a process crash, or power loss cannot execute a shell cleanup hook. post: never invokes the LLM.

Post hooks receive .Result, the execution result before cleanup: Name, Status (completed, failed, cancelled, timed_out), Error, TotalKnown, Total, Completed, Failed, Unprocessed, and Items. Each item has Item, Status, Attempts and Error. Items are recorded after their last attempt; --start excludes work from Total. If enumeration failed, TotalKnown is false. .Result.Summary produces a compact coverage report. The same report is printed at execution exit, including when debug output is disabled.

completed means the commands returned without an execution error. It does not validate a model’s answer, classify service health, or prove a notification was sent. Check actual tool receipts for delivery; model text and compaction summaries are not receipts. Post-hook failures are reported separately and do not retroactively change the result supplied to those hooks.

post:
  - >-
    if [ $[[ .Result.Status | shellQuote ]] != completed ]; then
      printf '%s\n' $[[ .Result.Summary | shellQuote ]];
    fi

Per-item receipts also contain Duration (nanoseconds), Reason, and Metrics (Iterations, InputTokens, OutputTokens, Compactions, CompactionTime in nanoseconds). Metrics accumulate across commands and session resets; they do not include work inside arbitrary shell subprocesses. A child Aura task produces its own receipt.

Reasons include max_steps, token_budget, policy_stopped, compaction_deadline, compaction_exhausted, tool_parse, context_overflow, deadline, cancelled, and execution_error. They describe execution, not whether an answer was correct. An opt-in response-validation plugin can require the agent’s declared output contract.

Use a stdin here-document containing $[[ .Result | toJson ]] to pass a structured result to a reporting command; large foreach reports should not be stored in environment variables or command-line arguments. This uses the existing post lifecycle; no additional failure hook is required.

For a task using a local Ollama provider, unload its selected model on exit:

post:
  - >-
    curl --fail --silent --show-error --connect-timeout 5 --max-time 15
    --json "$(jq -cn --arg model $[[ .Model.Name | shellQuote ]] '{model: $model, keep_alive: 0}')"
    $[[ printf "%s/api/generate" (trimSuffix "/" .Provider.URL) | shellQuote ]] > /dev/null

This is task-owned Ollama cleanup, not a provider-independent unload API. It targets the final selected model, not every model used by earlier switches or subagents. Do not use it where another workload must keep that model loaded. finally: remains assistant commands after a foreach loop; it is not the unconditional cleanup hook.

Foreach

Iterate over lines from a file or shell command. Each iteration expands runtime template variables.

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
    continue_on_error: true
    retries: 1
  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."

Field	Description
`file:`	Read lines from a file (one per line, empty lines filtered)
`shell:`	Run a command and read lines from stdout
`continue_on_error:`	Log per-item errors and continue instead of aborting; the task’s original timeout still applies
`retries:`	Additional attempts per failed item (0 = no retry)

The timeout is one wall-clock budget for the whole invocation, including all items and retries, in both scheduled and immediate runs. Expiry stops further work even with continue_on_error: true. The post cleanup hooks still run under their separate post_timeout budget.

A child task’s foreach block replaces the entire inherited block. Omit it to inherit the parent’s source and options. When overriding it, repeat any options you want to keep, such as continue_on_error: true; a new file source does not retain an inherited shell source.

finally: runs once after all iterations through the assistant.

Concurrency

--concurrency N caps total parallel task executions (default 1 = sequential).
In scheduler mode, if a task is still running when its next trigger fires, the trigger is skipped.

Examples

# Start the scheduler for all scheduled tasks
aura tasks run

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

# Run with command override
aura tasks run --now daily-review --prepend "/mode Ask"

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