> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentastic.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# dev task CLI reference

> Manage Agentastic scheduled tasks from the terminal. Create, list, run, pause, resume, and delete tasks using the dev task command.

The `dev task` command manages Agentastic scheduled tasks through the app's local IPC socket. Use it to create recurring or one-time tasks, check execution history, and control task state — all from the terminal or from within an agent workflow.

## Usage

```bash theme={null}
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]
```

## Commands

### List tasks

Returns all scheduled tasks and their latest execution summary.

```bash theme={null}
dev task list
```

### View history

Returns the execution history for all tasks, or for a specific task by ID.

```bash theme={null}
dev task history
dev task history 8F9F52A8-7E4B-4B5D-B9D7-3D6F3F70D197
```

### Run a task manually

Trigger a task immediately, regardless of its schedule.

```bash theme={null}
dev task run 8F9F52A8-7E4B-4B5D-B9D7-3D6F3F70D197
```

### Pause and resume

Pause a task to stop it from running on its schedule, or resume it to re-enable it.

```bash theme={null}
dev task pause 8F9F52A8-7E4B-4B5D-B9D7-3D6F3F70D197
dev task resume 8F9F52A8-7E4B-4B5D-B9D7-3D6F3F70D197
```

### Delete

Permanently remove a task.

```bash theme={null}
dev task delete 8F9F52A8-7E4B-4B5D-B9D7-3D6F3F70D197
```

## Creating tasks

Use `dev task create` with `--name`, `--command`, and `--schedule` to create a new task. The `--schedule` flag determines the schedule type and which additional flags are required.

### Once

Run a task a single time at a specific date and time.

```bash theme={null}
dev task create \
  --name "Release Notes" \
  --command "npm run release:notes" \
  --schedule once \
  --run-at 2026-03-16T18:00:00Z
```

### Interval

Run a task repeatedly at a fixed interval in seconds.

```bash theme={null}
dev task create \
  --name "Health Check" \
  --command "./scripts/health-check.sh" \
  --schedule interval \
  --interval-seconds 900
```

### Daily

Run a task every day at a specific hour and minute.

```bash theme={null}
dev task create \
  --name "Daily Tests" \
  --command "npm test" \
  --schedule daily \
  --hour 9 \
  --minute 0
```

### Weekly

Run a task on a specific day of the week at a specific time. The `--weekday` flag accepts values 0 (Sunday) through 6 (Saturday).

```bash theme={null}
dev task create \
  --name "Weekly Cleanup" \
  --command "./scripts/cleanup.sh" \
  --schedule weekly \
  --weekday 1 \
  --hour 8 \
  --minute 30
```

### Monthly

Run a task on a specific day of the month at a specific time.

```bash theme={null}
dev task create \
  --name "Monthly Report" \
  --command "bundle exec rake report:monthly" \
  --schedule monthly \
  --day 1 \
  --hour 7 \
  --minute 0
```

### Cron

Run a task on a custom cron schedule.

```bash theme={null}
dev task create \
  --name "Weekday Lint" \
  --command "npm run lint" \
  --schedule cron \
  --cron "0 10 * * 1,2,3,4,5"
```

## Updating tasks

Use `dev task update` to change a task's name, command, or schedule. Pass `--task-id` to identify the task, then include any fields you want to update.

```bash theme={null}
dev task update \
  --task-id 8F9F52A8-7E4B-4B5D-B9D7-3D6F3F70D197 \
  --name "Updated Task Name" \
  --command "npm run new-command"
```

## Optional flags

The following flags are available on both `create` and `update` commands.

| Flag                                  | Description                                                                                |
| ------------------------------------- | ------------------------------------------------------------------------------------------ |
| `--working-directory <relative-path>` | Working directory for the task, relative to the selected workspace, repo, or worktree root |
| `--workspace-url <file-url>`          | Target a specific workspace by file URL                                                    |
| `--repo-url <file-url>`               | Target a specific repository by file URL                                                   |
| `--worktree-url <file-url>`           | Target a specific worktree by file URL                                                     |
| `--max-concurrency <n>`               | Maximum number of concurrent executions                                                    |

<Note>
  Working directories must be relative to the selected workspace, repo, or worktree root — not absolute paths.
</Note>