> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coconut.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# nut task
> Manage tasks (change proposals)
# `nut task`
Manage tasks (change proposals) in your Coconut instance.
```bash theme={null}
nut task [command]
```
**Aliases:** `task`, `proposal`
## Overview
Tasks (also known as change proposals) are the core unit of work in Coconut. They represent features, bugs, refactors, or any change you want to implement in your codebase. The `nut task` command provides comprehensive management of tasks throughout their lifecycle.
`nut task` manages tasks in the current local workspace. To list, create, or update tasks on a remote peer Coconut through the Coconut Dashboard, use [`nut coconut task`](/cli/coconut).
***
## `nut task list`
List all tasks in your repository.
```bash theme={null}
nut task list [options]
```
**Options:**
* `--status ` - Filter by status (draft, backlog, ready, queued, active, blocked, review, done, canceled, duplicate)
* `--search ` - Search tasks by text
* `--json` - Output as JSON
**Examples:**
```bash theme={null}
# List all tasks
nut task list
# Filter by status
nut task list --status draft
nut task list --status active
# Search for specific tasks
nut task list --search "authentication"
```
***
## `nut task get`
Get detailed information about a specific task.
```bash theme={null}
nut task get
```
**Arguments:**
* `id` - The task ID (e.g., `cp-1234567890`)
**Options:**
* `--json` - Output as JSON
**Examples:**
```bash theme={null}
nut task get cp-1234567890
nut task get cp-1234567890 --json
```
***
## `nut task create`
Create a new task.
```bash theme={null}
nut task create [options]
```
**Arguments:**
* `title` - Title or description of the task
**Options:**
* `-p, --priority <level>` - Set priority (low, medium, high, critical)
* `-t, --tags <tags>` - Comma-separated tags
* `-s, --status <status>` - Initial status (draft, backlog, ready, queued, active, blocked, review, done, canceled, duplicate)
* `--author <name>` - Author name
* `--email <email>` - Author email
* `--type <type>` - Author type (`human` or `agent`, default: `human`)
* `-c, --content <text>` - Detailed description or content for the task
* `-f, --file <path>` - Read content from a file
* `-r, --readiness <score>` - Readiness score (0–100)
* `--spec <ref>` - Product specification reference
* `--json` - Output as JSON
* `-y, --yes` - Skip confirmation prompts
**Examples:**
```bash theme={null}
# Create a simple task
nut task create "Add user authentication"
# Create with priority and tags
nut task create "Fix bug in payment processing" -p high -t "bug,urgent"
# Create with specific status
nut task create "Refactor database layer" --priority medium --tags "refactor"
# Create with detailed content
nut task create "Implement OAuth2 flow" -c "Support Google and GitHub providers with refresh token rotation"
# Create from a spec file
nut task create "Build notification system" --file spec/notifications.md --spec "SPEC-42"
# Create and skip confirmation
nut task create "Quick fix for typo" -p low -y
```
<Tip>
Clear, descriptive intents help AI skills better understand and implement tasks. Use `-c` or `-f` to provide additional context that helps agents plan implementation.
</Tip>
***
## `nut task update`
Update an existing task's properties.
```bash theme={null}
nut task update <id> [options]
```
**Arguments:**
* `id` - The task ID to update
**Options:**
* `-t, -i, --title, --intent <text>` - Update title (aliases: -i, --intent)
* `-c, --content <text>` - Update content
* `-f, --file <path>` - Read new content from a file
* `-s, --status <status>` - Update status (draft, backlog, ready, queued, active, blocked, review, done, canceled, duplicate)
* `-p, --priority <level>` - Update priority (low, medium, high, critical)
* `--tags <tags>` - Update tags (comma-separated)
* `--spec <ref>` - Update product specification reference
* `--json` - Output as JSON
**Examples:**
```bash theme={null}
# Update task status
nut task update cp-1234567890 --status review
# Change priority
nut task update cp-1234567890 --priority critical
# Update title
nut task update cp-1234567890 --title "New task title"
# Update content from file
nut task update cp-1234567890 --file path/to/content.md
# Update multiple properties
nut task update cp-1234567890 --status done --priority low --tags "completed,deployed"
```
***
## `nut task step`
Add a plan step to a task.
```bash theme={null}
nut task step <id> <description> [options]
```
**Arguments:**
* `id` - The task ID
* `description` - Description of the step
**Options:**
* `--command <cmd>` - Optional command to execute for this step
**Examples:**
```bash theme={null}
# Add a simple plan step
nut task step cp-1234567890 "Implement user authentication"
# Add step with command
nut task step cp-1234567890 "Run tests" --command "npm test"
# Add multiple steps
nut task step cp-1234567890 "Create database schema"
nut task step cp-1234567890 "Implement API endpoints"
nut task step cp-1234567890 "Add frontend components"
```
<Note>
Plan steps help break down complex tasks into manageable pieces and provide structure for implementation.
</Note>
***
## `nut task comment`
Add a comment to a task.
```bash theme={null}
nut task comment <id> <content> [options]
```
**Arguments:**
* `id` - The task ID
* `content` - Comment text
**Options:**
* `--author <email>` - Comment author (defaults to current user)
**Examples:**
```bash theme={null}
# Add a comment
nut task comment cp-1234567890 "Looks good, approved!"
# Add comment with specific author
nut task comment cp-1234567890 "Please review" --author "reviewer@example.com"
# Add detailed feedback
nut task comment cp-1234567890 "Great work! Just need to update the tests before merging."
```
***
## `nut task delete`
Delete a task.
```bash theme={null}
nut task delete <id>
```
**Arguments:**
* `id` - The task ID to delete
**Examples:**
```bash theme={null}
nut task delete cp-1234567890
```
<Note>
Deleting a task is permanent. Make sure you want to remove it before confirming.
</Note>
***
## Complete Workflow Example
Here's a complete workflow using task commands:
<Steps>
<Step title="Create a task">
```bash theme={null}
nut task create "Add dark mode support" --priority high --tags "feature,ui"
```
Returns: `Created task cp-1234567890`
</Step>
<Step title="Add plan steps">
```bash theme={null}
nut task step cp-1234567890 "Add theme toggle component"
nut task step cp-1234567890 "Update CSS variables for dark mode"
nut task step cp-1234567890 "Add user preference persistence"
nut task step cp-1234567890 "Test in all browsers" --command "npm run test:e2e"
```
</Step>
<Step title="Start implementation">
```bash theme={null}
nut code cp-1234567890
```
</Step>
<Step title="Update status">
```bash theme={null}
nut task update cp-1234567890 --status review
```
</Step>
<Step title="Add review comments">
```bash theme={null}
nut task comment cp-1234567890 "Implementation complete, ready for review"
```
</Step>
<Step title="Mark complete">
```bash theme={null}
nut task update cp-1234567890 --status done
```
</Step>
</Steps>
## Finding Task IDs
If you need to find a task ID:
1. Use `nut task list` to see all tasks
2. Use `nut task list --search "keyword"` to search
3. Task IDs follow the format `cp-XXXXXXXXXX`