---
title: "Tasks CLI"
canonical: https://workspace.socra.com/docs/tasks/reference/cli
---

# 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](https://cli.socra.com) installed, add the Tasks plugin:

```sh
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:

```sh
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](/docs/tasks/scheduling) 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.