cli-usage

What this skill does

# MCP-Tasks CLI Reference

This skill provides comprehensive CLI reference for the mcp-tasks command-line tool.

## Overview

The mcp-tasks CLI provides task management via command-line interface for scripting and automation. For agent workflows, use the MCP server instead.

## Installation

The CLI is distributed as a pre-built Babashka uberscript in this plugin:
```bash
plugins/mcp-tasks-cli/bin/mcp-tasks
```

Add to PATH or invoke directly:
```bash
# Add to PATH (example)
export PATH="$PATH:/path/to/plugins/mcp-tasks-cli/bin"

# Or invoke directly
/path/to/plugins/mcp-tasks-cli/bin/mcp-tasks --help
```

## Configuration Discovery

No `--config-path` required. The CLI automatically searches for `.mcp-tasks.edn`:
- Starts from current directory
- Traverses up directory tree
- Stops at filesystem root or when found

Example:
```bash
# Project structure:
# /project/.mcp-tasks.edn
# /project/src/

# Works from any subdirectory:
cd /project/src
mcp-tasks list  # Finds /project/.mcp-tasks.edn
```

## Commands

| Command | Purpose | Required Args | Key Options |
|---------|---------|---------------|-------------|
| `list` | Query tasks with filters | None | `--status`, `--category`, `--type`, `--parent-id`, `--task-id`, `--title-pattern`, `--limit`, `--unique` |
| `show` | Display single task | `--task-id` | `--format` |
| `add` | Create new task | `--category`, `--title` | `--description`, `--type`, `--parent-id`, `--prepend` |
| `complete` | Mark task complete | `--task-id` or `--title` | `--category`, `--completion-comment` |
| `update` | Update task fields | `--task-id` | `--title`, `--description`, `--design`, `--status`, `--category`, `--type`, `--parent-id`, `--meta`, `--relations` |
| `delete` | Delete task | `--task-id` or `--title-pattern` | None |

## Global Options

| Option | Values | Default | Description |
|--------|--------|---------|-------------|
| `--format` | `edn`, `json`, `human` | `edn` | Output format |
| `--help` | - | - | Show help message |

## Command Details

### list

Query tasks with optional filters.

**Usage:**
```bash
mcp-tasks list [options]
```

**Options:**

| Flag | Alias | Type | Description |
|------|-------|------|-------------|
| `--status` | `-s` | keyword | Filter by status: `open`, `closed`, `in-progress`, `blocked`, `any` |
| `--category` | `-c` | string | Filter by category name |
| `--type` | `-t` | keyword | Filter by type: `task`, `bug`, `feature`, `story`, `chore` |
| `--parent-id` | `-p` | integer | Filter by parent task ID |
| `--task-id` | - | integer | Filter by specific task ID |
| `--title-pattern` | `--title` | string | Filter by title pattern (regex or substring) |
| `--limit` | - | integer | Maximum tasks to return (default: 30) |
| `--unique` | - | boolean | Enforce 0 or 1 match (error if >1) |
| `--format` | - | keyword | Output format: `edn`, `json`, `human` |

**Examples:**
```bash
# List open tasks in human format
mcp-tasks list --status open --format human

# List all tasks for a category
mcp-tasks list --status any --category simple

# List story child tasks
mcp-tasks list --parent-id 31 --status open
```

### show

Display a single task by ID.

**Usage:**
```bash
mcp-tasks show --task-id <id> [options]
```

**Options:**

| Flag | Alias | Type | Required | Description |
|------|-------|------|----------|-------------|
| `--task-id` | `--id` | integer | Yes | Task ID to display |
| `--format` | - | keyword | No | Output format: `edn`, `json`, `human` |

**Examples:**
```bash
# Show task in EDN format
mcp-tasks show --task-id 42

# Show task in human-readable format
mcp-tasks show --id 42 --format human
```

### add

Create a new task.

**Usage:**
```bash
mcp-tasks add --category <name> --title <title> [options]
```

**Options:**

| Flag | Alias | Type | Required | Description |
|------|-------|------|----------|-------------|
| `--category` | `-c` | string | Yes | Task category (e.g., `simple`, `medium`, `large`) |
| `--title` | `-t` | string | Yes | Task title |
| `--description` | `-d` | string | No | Task description |
| `--type` | - | keyword | No | Task type (default: `task`). Options: `task`, `bug`, `feature`, `story`, `chore` |
| `--parent-id` | `-p` | integer | No | Parent task ID (for child tasks) |
| `--prepend` | - | boolean | No | Add task at beginning instead of end |
| `--format` | - | keyword | No | Output format: `edn`, `json`, `human` |

**Examples:**
```bash
# Create simple task
mcp-tasks add --category simple --title "Fix parser bug"

# Create task with description
mcp-tasks add -c medium -t "Add auth" -d "Implement JWT auth"

# Create child task
mcp-tasks add --category simple --title "Subtask" --parent-id 31
```

### complete

Mark a task as complete and move to archive.

**Usage:**
```bash
mcp-tasks complete (--task-id <id> | --title <pattern>) [options]
```

**Options:**

| Flag | Alias | Type | Required | Description |
|------|-------|------|----------|-------------|
| `--task-id` | `--id` | integer | * | Task ID to complete |
| `--title` | `-t` | string | * | Task title pattern (alternative to task-id) |
| `--category` | `-c` | string | No | Task category (for verification) |
| `--completion-comment` | `--comment` | string | No | Optional completion comment |
| `--format` | - | keyword | No | Output format: `edn`, `json`, `human` |

\* At least one of `--task-id` or `--title` required.

**Examples:**
```bash
# Complete by ID
mcp-tasks complete --task-id 42

# Complete by title with comment
mcp-tasks complete --title "Fix bug" --comment "Fixed via PR #123"

# Complete with category verification
mcp-tasks complete --id 42 --category simple
```

### update

Update task fields.

**Usage:**
```bash
mcp-tasks update --task-id <id> [options]
```

**Options:**

| Flag | Alias | Type | Required | Description |
|------|-------|------|----------|-------------|
| `--task-id` | `--id` | integer | Yes | Task ID to update |
| `--title` | `-t` | string | No | New task title |
| `--description` | `-d` | string | No | New task description |
| `--design` | - | string | No | New task design notes |
| `--status` | `-s` | keyword | No | New status: `open`, `closed`, `in-progress`, `blocked` |
| `--category` | `-c` | string | No | New task category |
| `--type` | - | keyword | No | New task type: `task`, `bug`, `feature`, `story`, `chore` |
| `--parent-id` | `-p` | integer/string | No | New parent task ID (pass `"null"` to remove) |
| `--meta` | - | JSON string | No | New metadata as JSON object (replaces entire map) |
| `--relations` | - | JSON string | No | New relations as JSON array (replaces entire vector) |
| `--format` | - | keyword | No | Output format: `edn`, `json`, `human` |

**Examples:**
```bash
# Update status
mcp-tasks update --task-id 42 --status in-progress

# Update title and description
mcp-tasks update --id 42 --title "New title" --description "New desc"

# Update metadata
mcp-tasks update --task-id 42 --meta '{"priority":"high"}'

# Remove parent relationship
mcp-tasks update --task-id 42 --parent-id "null"
```

### delete

Delete a task from tasks.ednl (archives to complete.ednl with `:status :deleted`).

**Usage:**
```bash
mcp-tasks delete (--task-id <id> | --title-pattern <pattern>) [options]
```

**Options:**

| Flag | Alias | Type | Required | Description |
|------|-------|------|----------|-------------|
| `--task-id` | `--id` | integer | * | Task ID to delete |
| `--title-pattern` | `--title` | string | * | Title pattern to match (alternative to task-id) |
| `--format` | - | keyword | No | Output format: `edn`, `json`, `human` |

\* At least one of `--task-id` or `--title-pattern` required.

**Constraints:**
- Cannot delete tasks with non-closed children (must complete or delete children first)

**Examples:**
```bash
# Delete by ID
mcp-tasks delete --task-id 42

# Delete by title pattern
mcp-tasks delete --title-pattern "old-task"

# Delete with human-readable output
mcp-tasks delete --id 42 --format human
```

## Output Formats

### EDN (Default)

Clojure ED