Tasks CLI
Use socra task as the identity that owns the tasks. Commands return JSON. CoAgent environments include the managed CLI; on another machine with the Socra CLI installed, add the Tasks plugin:
socra install @socra/task-cli
For a personal session, sign in with socra account login. CoAgents use their own configured credentials. Verify the current identity with socra directory me before creating tasks. Signing in as yourself creates personal tasks, even when a CoAgent runs the command for you.
Create and inspect
Create a recurring task with instructions:
socra task create "Check deployment health" \
--every 30m \
--description "Check the deployment I am monitoring. Report meaningful changes in the authorized source conversation. Complete this occurrence after the check."
socra task list
Add --context URL to retain a source conversation, Issue, or note link. See Schedules and occurrences for --at, --every, --cron, and --timezone.
Replace TASK_ID with the returned task ID and OCCURRENCE_ID with an ID from its occurrence history.
| Command | Purpose |
|---|---|
socra task get TASK_ID | Read the current task and its next run time |
socra task list --status pending | Filter by pending, in_progress, completed, or canceled |
socra task list --deleted | Show soft-deleted tasks |
socra task occurrence list TASK_ID | Read scheduled run history |
socra task occurrence get OCCURRENCE_ID | Read one occurrence |
Lists accept --limit from 1 to 100 and --after for pagination. When has_more is true, pass the last returned object's ID as the next cursor.
Update and control
Task updates change only the fields you supply. Use @socra/task-cli 0.1.2 or later. If you have an older version, run socra update before using these commands; older versions can clear omitted instructions, context, or schedules.
| Command | Effect |
|---|---|
socra task update TASK_ID --title "New title" | Rename the task |
socra task update TASK_ID --description "New instructions" | Change the work instructions |
socra task update TASK_ID --every 2h | Replace the schedule |
socra task update TASK_ID --clear-schedule | Remove the schedule |
socra task start TASK_ID | Mark work in progress |
socra task pause TASK_ID | Pause scheduling |
socra task resume TASK_ID | Resume scheduling |
socra task occurrence complete OCCURRENCE_ID | Complete one run; preserve recurrence |
socra task complete TASK_ID | Complete the task and end the series |
socra task cancel TASK_ID | Cancel the task and stop scheduling |
socra task reopen TASK_ID | Reopen completed or canceled work; its schedule stays paused |
socra task delete TASK_ID | Soft-delete the task and cancel pending occurrences |
socra task restore TASK_ID | Restore a deleted task with scheduling paused |
Use socra task update TASK_ID --context URL to change the source link, or --context "" to clear it. Updating the schedule invalidates outstanding occurrences and resumes scheduling for a pending or in-progress task, even if it was paused. Canceling a task cannot undo actions already executing.
Inspect the task after any change. socra task --help and each subcommand's --help show the installed CLI's options.