Tasks
Every command for tasks, the runs they make and the approvals those runs ask for, with worked examples.
How it fits together
A task is an instruction the assistant runs by itself, with a trigger that starts it and an autonomy that says how much it may change without asking. Each run leaves a record, and anything it may not do alone waits as an approval request. Reading needs tasks:read with threads:read and emails:read. Creating, changing, resuming, running and approving need tasks:write with threads:read, threads:write, emails:read, emails:send and labels:write, and the scopes of each toolkit. Reading a run or one of its approval requests also needs the read scopes of every toolkit the run used. Without them, a list shows such a run without its report and its requests without their arguments. Approving counts the toolkits the run started with, plus the scopes of the tool the request would call.
nextmail tasks create --name "Morning summary" --instruction "Tell me which conversations need a reply, most urgent first." --trigger-kind schedule --trigger-schedule-cadence daily --trigger-schedule-hour 8 --trigger-schedule-timezone Europe/Londonnextmail tasks run tsk_5c1e9a7b3d2f48e6a0b4c7d1nextmail tasks get-run run_2b8d4f6a1c3e5079b6d8f0a2nextmail tasks list-approvalsnextmail tasks approve apr_9f3a1c5e7b2d4608a1c3e5f7A trigger with many parts is easier as JSON: write the task to a file and pass it with --data @task.json. nextmail tasks get <id> --json prints one in that shape.
A task whose toolkits hold connectors may use the apps connected for the workspace, never a connector that belongs to one person, and it then also needs connectors:read and connectors:use. Such a run reads through a connector alone, every change in an app waits as an approval request whatever the autonomy, and with reply every answer to an email waits for approval as well. A connector read that names a web address waits for approval too.
Tasks
| Command | What it does |
|---|---|
| nextmail tasks list | One page of the tasks, most recently changed first. --status narrows it to active or paused |
| nextmail tasks create --name <value> --instruction <value> --trigger-kind <kind> | Save a task and turn it on. --trigger-kind is schedule, mail or manual, --autonomy is ask, organize or reply, and --paused saves it without turning it on |
| nextmail tasks get <id> | One task with its trigger, its settings and its last and next run |
| nextmail tasks update <id> | Change what you pass and leave the rest. A new trigger replaces the old one whole |
| nextmail tasks pause <id> | Stop a task from starting runs. A run already going carries on |
| nextmail tasks resume <id> | Turn a paused task back on and clear its count of failed runs |
| nextmail tasks run <id> | Start a run now, whatever the trigger, and print the run |
| nextmail tasks delete <id> | Delete a task for good with every run it made, once you confirm |
Runs
| Command | What it does |
|---|---|
| nextmail tasks list-runs | Runs across the workspace, newest first. --task-id and --status narrow it |
| nextmail tasks get-run <id> | One run with every step it took, the tools it called and what it asked |
| nextmail tasks start-run --instruction <value> | Hand the assistant one job to do in the background, with no task saved |
| nextmail tasks cancel-run <id> | Stop a run that is queued, running or waiting, once you confirm. What it did stays done |
nextmail tasks start-run --instruction "Find every invoice that arrived this month and label it Invoices." --autonomy organize --max-steps 30nextmail tasks list-runs --status waitingnextmail tasks get-run run_2b8d4f6a1c3e5079b6d8f0a2 --jsonA run is queued, then running, then waiting while a request is open, and ends done, failed or cancelled. get-run --json prints the transcript, so a script can read it again until the status settles.
Approvals
| Command | What it does |
|---|---|
| nextmail tasks list-approvals | What runs are waiting for you to allow, newest first. --task-id, --run-id and --status narrow it |
| nextmail tasks get-approval <id> | One request with the tool and the exact arguments it would be called with |
| nextmail tasks approve <id> | Let it happen, once you confirm. --subject and --body replace the words of a send or a reply |
| nextmail tasks deny <id> | Refuse it, once you confirm. The run is told and carries on without it |
A request waits 7 days and then expires, which the run reads as a refusal. --yes skips the confirmation in a script.