Tasks CLI

Use socra task as the identity that owns the tasks. Commands return JSON. Socra Agent 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. Agents 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 an agent 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

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 the task with scheduling 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. 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.

Open Markdown