Pipe Interface

Pipe Interface

Scripting interface for external tool integration via stdin/stdout.

---

Overview

The pipe interface allows external scripts and tools to interact with TaskFlow programmatically. Commands are sent as JSON objects to stdin, and responses are returned on stdout in JSON, YAML, or CSV format.

---

Basic Usage

taskflow pipe [--format json|yaml|csv]

The pipe command reads JSON commands line by line from stdin, processes each command, and writes the response to stdout.

---

Output Formats

Format	Flag	Best For
JSON	--format json (default)	APIs, scripts, parsing
YAML	--format yaml	Human-readable output
CSV	--format csv	Spreadsheets, data analysis

Note: CSV format only works for list operations. Other operations fall back to JSON.

---

Request Format

All requests are JSON objects with these fields:

{
  "operation": "list|get|create|update|delete|export|import",
  "entity": "task|project|time_entry|work_log|habit|goal|key_result|tag|saved_filter",
  "id": "uuid",
  "data": { ... },
  "filters": { ... }
}

Field	Required	Description
operation	Yes	The operation to perform
entity	Yes	The entity type to operate on
id	For get/update/delete	Entity UUID
data	For create/update/import	Entity data
filters	For list	Filter and pagination options

---

Response Format

Success Response

{
  "success": true,
  "data": { ... },
  "error": null,
  "metadata": {
    "total": 42,
    "offset": 0,
    "limit": 100
  }
}

Error Response

{
  "success": false,
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Task not found: uuid",
    "details": null
  }
}

---

Operations

List

Retrieve multiple entities with optional filtering and pagination.

echo '{"operation":"list","entity":"task"}' | taskflow pipe

Get

Retrieve a single entity by ID.

echo '{"operation":"get","entity":"task","id":"uuid"}' | taskflow pipe

Create

Create a new entity.

echo '{"operation":"create","entity":"task","data":{"title":"Buy milk"}}' | taskflow pipe

Update

Update an existing entity. Only provided fields are updated.

echo '{"operation":"update","entity":"task","id":"uuid","data":{"status":"done"}}' | taskflow pipe

Delete

Delete an entity.

echo '{"operation":"delete","entity":"task","id":"uuid"}' | taskflow pipe

Export

Export all data.

echo '{"operation":"export","entity":"task"}' | taskflow pipe --format yaml > backup.yaml

Import

Import data from an export.

cat backup.json | jq '{operation:"import",entity:"task",data:.}' | taskflow pipe

---

Filtering (List Operations)

{
  "operation": "list",
  "entity": "task",
  "filters": {
    "project_id": "uuid",
    "tags": ["work", "urgent"],
    "tags_mode": "any",
    "status": ["todo", "in_progress"],
    "priority": ["high", "urgent"],
    "search": "text to search",
    "include_completed": false,
    "due_before": "2025-12-31",
    "due_after": "2025-01-01",
    "sort_by": "due_date",
    "sort_order": "asc",
    "limit": 100,
    "offset": 0
  }
}

Filter	Description
project_id	Filter by project UUID
tags	Filter by tags (array)
tags_mode	"all" (default) or "any"
status	Filter by status values
priority	Filter by priority values
search	Full-text search in title, description, tags
include_completed	Include completed tasks (default: false)
due_before	Due date before (YYYY-MM-DD)
due_after	Due date after (YYYY-MM-DD)
sort_by	Sort field: due_date, priority, title, created, updated
sort_order	"asc" or "desc"
limit	Max results (default: 100)
offset	Skip first N results

---

Entity Types

Task

Create/Update fields:

{
  "title": "Task title",
  "description": "Optional description",
  "status": "todo|in_progress|blocked|done|cancelled",
  "priority": "none|low|medium|high|urgent",
  "project_id": "uuid",
  "tags": ["tag1", "tag2"],
  "due_date": "2025-12-31",
  "scheduled_date": "2025-12-25",
  "estimated_minutes": 60,
  "dependencies": ["uuid1", "uuid2"]
}

Project

{
  "name": "Project name",
  "description": "Optional description",
  "color": "#FF5733",
  "archived": false
}

Time Entry

{
  "task_id": "uuid",
  "description": "What I worked on",
  "started_at": "2025-12-11T10:00:00Z",
  "ended_at": "2025-12-11T11:30:00Z",
  "duration_minutes": 90
}

Work Log

{
  "task_id": "uuid",
  "content": "What I accomplished",
  "logged_at": "2025-12-11T12:00:00Z"
}

Habit

{
  "name": "Exercise",
  "description": "30 minutes of activity",
  "frequency": "daily|weekly|every_3_days",
  "tags": ["health"]
}

Goal

{
  "name": "Q1 Objectives",
  "description": "Quarterly goals",
  "target_date": "2025-03-31"
}

Key Result

{
  "goal_id": "uuid",
  "name": "Increase revenue",
  "target_value": 100000.0,
  "current_value": 50000.0,
  "unit": "USD"
}

Tag

Tags are read-only (derived from tasks and habits).

# List all tags with usage counts
echo '{"operation":"list","entity":"tag"}' | taskflow pipe

# Get details for a specific tag
echo '{"operation":"get","entity":"tag","id":"work"}' | taskflow pipe

---

Error Codes

Code	Description
PARSE_ERROR	Failed to parse JSON request
INVALID_OPERATION	Unknown operation
INVALID_ENTITY	Unknown entity type
MISSING_ID	ID required but not provided
INVALID_ID	ID is not a valid UUID
MISSING_DATA	Data required but not provided
INVALID_DATA	Data failed validation
NOT_FOUND	Entity not found
IO_ERROR	Failed to read stdin

---

Examples

List Today's Tasks

echo '{
  "operation": "list",
  "entity": "task",
  "filters": {
    "due_before": "2025-12-12",
    "due_after": "2025-12-11"
  }
}' | taskflow pipe

Create a Task with Tags and Due Date

echo '{
  "operation": "create",
  "entity": "task",
  "data": {
    "title": "Review quarterly report",
    "priority": "high",
    "tags": ["work", "reports"],
    "due_date": "2025-12-15"
  }
}' | taskflow pipe

Mark Task as Complete

echo '{
  "operation": "update",
  "entity": "task",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {"status": "done"}
}' | taskflow pipe

Filter Tasks by Multiple Tags

echo '{
  "operation": "list",
  "entity": "task",
  "filters": {
    "tags": ["work", "urgent"],
    "tags_mode": "any",
    "status": ["todo", "in_progress"]
  }
}' | taskflow pipe

Export to YAML Backup

echo '{"operation":"export","entity":"task"}' | taskflow pipe --format yaml > backup.yaml

Export Tasks as CSV

echo '{"operation":"list","entity":"task"}' | taskflow pipe --format csv > tasks.csv

Batch Operations

# Process multiple commands
cat << 'EOF' | taskflow pipe
{"operation":"create","entity":"task","data":{"title":"Task 1"}}
{"operation":"create","entity":"task","data":{"title":"Task 2"}}
{"operation":"list","entity":"task","filters":{"limit":5}}
EOF

Script Integration

#!/bin/bash
# Count high priority tasks

count=$(echo '{
  "operation": "list",
  "entity": "task",
  "filters": {"priority": ["high", "urgent"]}
}' | taskflow pipe | jq '.data.total')

echo "You have $count high priority tasks"

Integration with jq

# Get just task titles
echo '{"operation":"list","entity":"task"}' | taskflow pipe | jq -r '.data.tasks[].title'

# Get overdue task IDs
echo '{"operation":"list","entity":"task","filters":{"due_before":"2025-12-11"}}' \
  | taskflow pipe \
  | jq -r '.data.tasks[].id'

---

See Also

• CLI-Options - Command line options
• Import-Export - Bulk import/export
• Storage-Backends - Storage configuration