CLI Usage

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:

plugins/mcp-tasks-cli/bin/mcp-tasks

Add to PATH or invoke directly:

# 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:

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

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

Commands

Global Options

Command Details

list

Query tasks with optional filters.

Usage:

mcp-tasks list [options]

Options:

Examples:

# 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:

mcp-tasks show --task-id <id> [options]

Options:

Examples:

# 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:

mcp-tasks add --category <name> --title <title> [options]

Options:

Examples:

# 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:

mcp-tasks complete (--task-id <id> | --title <pattern>) [options]

Options:

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

Examples:

# 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:

mcp-tasks update --task-id <id> [options]

Options:

Examples:

# 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:

mcp-tasks delete (--task-id <id> | --title-pattern <pattern>) [options]

Options:

* 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:

# 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 EDN format suitable for programmatic consumption:

{:tasks [{:id 42 :title "Fix bug" :status :open ...}]
 :metadata {:open-task-count 5 :returned-count 1}}

JSON

JSON format for integration with non-Clojure tools:

{
  "tasks": [{"id": 42, "title": "Fix bug", "status": "open", ...}],
  "metadata": {"open_task_count": 5, "returned_count": 1}
}

Human

Human-readable tabular format:

Tasks (1 found, showing 1):

ID  | Status | Category | Type | Title
----|--------|----------|------|--------
42  | open   | simple   | task | Fix bug

Metadata:
  Open tasks: 5
  Returned: 1

Common Workflows

Query and Display

# Find tasks by status and category
mcp-tasks list --status open --category medium --format human

# Show specific task details
mcp-tasks show --task-id 42 --format human

Create and Manage Tasks

# Create simple task
mcp-tasks add --category simple --title "Fix parser"

# Create story with child tasks
mcp-tasks add --category large --title "User auth" --type story
mcp-tasks add --category medium --title "Login" --parent-id 100

# Update task status
mcp-tasks update --task-id 101 --status in-progress

# Complete task with comment
mcp-tasks complete --task-id 101 --comment "Implemented"

Scripting Examples

# Get open task count (JSON + jq)
mcp-tasks list --status open --format json | jq '.metadata.open_task_count'

# List all story tasks
mcp-tasks list --type story --status any --format human

# Batch update tasks (shell loop)
for id in 42 43 44; do
  mcp-tasks update --task-id $id --status closed
done

File Locations

The CLI operates on these files within the .mcp-tasks/ directory:

CLI vs MCP Server

Use CLI for:

• Shell scripting and automation
• CI/CD pipelines
• Batch operations
• Quick queries from terminal
• Integration with non-agent tools

Use MCP Server for:

• Agent-driven task execution
• Interactive task refinement
• Workflow automation with prompts
• Story-based development
• Git integration (branches, worktrees)

The CLI and MCP server operate on the same .mcp-tasks/ data files and can be used interchangeably.

Error Handling

Configuration not found:

Error: Could not find .mcp-tasks.edn in current directory or any parent directory

Solution: Initialize project with .mcp-tasks.edn or run from correct directory.

Unknown option:

Unknown option: --invalid. Use --help to see valid options.

Solution: Check command-specific help with mcp-tasks <command> --help.

Invalid format:

Invalid format: xml. Must be one of: edn, json, human

Solution: Use one of the supported format values.

Missing required argument:

Required option: --task-id (or --id)

Solution: Provide all required arguments for the command.

Task not found:

Error: No task found with task-id: 999

Solution: Verify task ID exists using mcp-tasks list.

Limitations

• No interactive prompts (use flags for all input)
• No task execution workflows (use MCP server)
• No git integration (use MCP server)
• No worktree management (use MCP server)
• No branch automation (use MCP server)

Version

Check version in plugins/mcp-tasks-cli/.claude-plugin/plugin.json.