DocsAutomation

Task CLI Reference

Manage scheduled Agentastic tasks from the dev CLI — creating tasks, persistent task memory, event triggers, and remote SSH tasks.

Overview#

The dev task command manages Agentastic scheduled tasks through the app's local IPC socket.

Usage#

bash

dev task list
dev task history [task-id]
dev task run <task-id>
dev task pause <task-id>
dev task resume <task-id>
dev task delete <task-id>
dev task create --name <name> --command <cmd> --schedule <kind> [options]
dev task update --task-id <id> [--name <name>] [--command <cmd>] [--schedule <kind>] [options]
dev task memory.read task_id=<id> [name=MEMORIES.md]
dev task memory.append task_id=<id> content=<markdown> [name=MEMORIES.md]
dev task trigger.event task_id=<id> trigger_id=<id> external_event_id=<id> [payload=<json>]

Commands#

List tasks#

bash

dev task list

Returns the current scheduled tasks and their latest execution summary.

View history#

bash

dev task history
dev task history 8F9F52A8-7E4B-4B5D-B9D7-3D6F3F70D197

Local agent tasks retain each agent's startup progress and worktree/terminal routing. In the app's task history, Open Agent opens that recorded worktree or terminal, including attempts that need attention.

Launched confirms startup; it does not track the agent's eventual outcome.
Waiting means startup needs input, or an interrupted dispatch could not be confirmed. Inspect the recorded agent before starting another run.
Automatic retries preserve the original child plan, reuse prepared worktrees, and skip agents already confirmed launched. A partial failure therefore does not restart successful agents.

Local launches wait through system sleep and a sleeping connected display. Startup continues when the execution environment is available again. Historical records that lost their routing before startup checkpoints were introduced are not backfilled.

Trigger a task manually#

bash

dev task run 8F9F52A8-7E4B-4B5D-B9D7-3D6F3F70D197

Pause or resume#

bash

dev task pause 8F9F52A8-7E4B-4B5D-B9D7-3D6F3F70D197
dev task resume 8F9F52A8-7E4B-4B5D-B9D7-3D6F3F70D197

Pausing holds queued automatic executions and prevents future schedule occurrences. Explicit dev task run requests can still run a paused task.

Delete#

bash

dev task delete 8F9F52A8-7E4B-4B5D-B9D7-3D6F3F70D197

Creating tasks#

One-time#

bash

dev task create \
  --name "Release Notes" \
  --command "npm run release:notes" \
  --schedule once \
  --run-at 2026-03-16T18:00:00Z

Interval#

bash

dev task create \
  --name "Health Check" \
  --command "./scripts/health-check.sh" \
  --schedule interval \
  --interval-seconds 900

Daily#

bash

dev task create \
  --name "Daily Tests" \
  --command "npm test" \
  --schedule daily \
  --hour 9 \
  --minute 0

Weekly#

bash

dev task create \
  --name "Weekly Cleanup" \
  --command "./scripts/cleanup.sh" \
  --schedule weekly \
  --weekday 1 \
  --hour 8 \
  --minute 30

Monthly#

bash

dev task create \
  --name "Monthly Report" \
  --command "bundle exec rake report:monthly" \
  --schedule monthly \
  --day 1 \
  --hour 7 \
  --minute 0

Cron#

bash

dev task create \
  --name "Weekday Lint" \
  --command "npm run lint" \
  --schedule cron \
  --cron "0 10 * * 1,2,3,4,5"

Optional flags#

bash

--working-directory <relative-path>
--workspace-url <file-url>
--repo-url <file-url>
--worktree-url <file-url>
--max-concurrency <n>

Working directories must be relative to the selected workspace, repo, or worktree root.

Persistent task memory#

Agent tasks can keep named memory documents outside the repository. MEMORIES.md is the default. Parallel agents should append so their writes are serialized without overwriting one another:

bash

dev task memory.read task_id=8F9F52A8-7E4B-4B5D-B9D7-3D6F3F70D197
dev task memory.append \
  task_id=8F9F52A8-7E4B-4B5D-B9D7-3D6F3F70D197 \
  name=MEMORIES.md \
  content="PR 123 fixes the checkout race; do not reopen it."

Manual replacements accept expected_revision=<n> and fail if another agent or user edited the document first.

Event trigger ingestion#

Configured GitHub, webhook, and plugin triggers accept verified events through local IPC. The external_event_id is idempotent for a trigger: replaying the same delivery does not enqueue a second run.

bash

dev task trigger.event \
  task_id=<task-id> \
  trigger_id=<trigger-id> \
  external_event_id=<provider-delivery-id> \
  payload='{"action":"opened"}'

This command is local ingestion, not a public webhook endpoint. A signed relay or provider plugin must authenticate external events before forwarding them. Tasks for local repositories still require Agentastic to be running; tasks for repositories on a Remote SSH host run on that host's agentastic-dev-server (0.9.12 or newer) even while your Mac is asleep. Team ownership and always-on relay execution are marked as coming soon in the UI.

Remote SSH tasks#

When a task's repository lives on a Remote SSH host, Agentastic stores the task on the host instead of in its local database and the host daemon schedules it. dev task list, history, run, pause, resume and delete work on remote tasks while the host is connected; the daemon keeps running them when it is not. Manage them from Remote Sessions → Scheduled Tasks or from the central task list.

If the host still runs an older agentastic-dev-server, the Scheduled Tasks tab and the task editor say so and offer an Upgrade Server button that redeploys the daemon in place. Upgrading restarts the daemon, which ends that host's remote terminal sessions.

Remote tasks run agents in a fresh worktree of the repository with exactly one Claude Code or Codex agent per task. With agentastic-dev-server 0.9.14 or newer, the agent runs in a persistent terminal on the host. When you reconnect, selecting its worktree opens the same agent and replays its output, including runs that finished while your Mac was asleep. The terminal remains available after the initial turn finishes. Plugins, task memory, event triggers and attachments are not available for remote runs yet. Runs created by older daemons retain their output in the task's run history.