Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/phodal/routa/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The routa task command group provides tools for managing tasks in Routa workspaces. Tasks represent discrete units of work that can be assigned to agents, tracked, and coordinated as part of larger workflows.

​
Task Statuses

Tasks progress through several statuses:
StatusDescription
PENDINGTask created but not yet started
IN_PROGRESSTask is actively being worked on
REVIEW_REQUIREDTask completed and awaiting review
COMPLETEDTask successfully finished
NEEDS_FIXTask requires corrections or improvements
BLOCKEDTask cannot proceed due to dependencies
CANCELLEDTask was cancelled

​
Commands

​
List Tasks

List all tasks in a workspace: 
routa task list [OPTIONS]
Options:
  • --workspace-id <ID> - Workspace ID (default: default)
Example: 
routa task list --workspace-id my-project
Output: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tasks": [
      {
        "id": "task_abc123",
        "title": "Implement user authentication",
        "objective": "Add OAuth 2.0 login with Google and GitHub providers",
        "status": "IN_PROGRESS",
        "assignedTo": "agent_def456",
        "workspaceId": "default",
        "createdAt": "2026-03-03T10:00:00Z",
        "updatedAt": "2026-03-03T11:30:00Z"
      },
      {
        "id": "task_xyz789",
        "title": "Add password reset flow",
        "objective": "Implement email-based password reset with security tokens",
        "status": "PENDING",
        "assignedTo": null,
        "workspaceId": "default",
        "createdAt": "2026-03-03T10:05:00Z",
        "updatedAt": "2026-03-03T10:05:00Z"
      }
    ]
  }
}

​
Create Task

Create a new task in a workspace: 
routa task create [OPTIONS]
Options:
  • --title <TITLE> - Task title (required)
  • --objective <TEXT> - Task objective description (required)
  • --workspace-id <ID> - Workspace ID (default: default)
  • --scope <TEXT> - Task scope description (optional)
  • --acceptance-criteria <CRITERIA> - Comma-separated acceptance criteria (optional)
Examples: 
# Basic task creation
routa task create \
  --title "Add user profile page" \
  --objective "Create a profile page showing user info and activity" \
  --workspace-id default

# Task with scope and acceptance criteria
routa task create \
  --title "Implement search feature" \
  --objective "Add full-text search across documents" \
  --workspace-id my-project \
  --scope "Search should cover titles, content, and metadata" \
  --acceptance-criteria "Search returns results in <200ms,Supports fuzzy matching,Results are paginated"
Output: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "taskId": "task_new123",
    "title": "Add user profile page",
    "objective": "Create a profile page showing user info and activity",
    "status": "PENDING",
    "workspaceId": "default",
    "scope": null,
    "acceptanceCriteria": [],
    "createdAt": "2026-03-03T12:00:00Z"
  }
}

​
Get Task

Get details of a specific task: 
routa task get --id <TASK_ID>
Options:
  • --id <ID> - Task ID (required)
Example: 
routa task get --id task_abc123
Output: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "task_abc123",
    "title": "Implement user authentication",
    "objective": "Add OAuth 2.0 login with Google and GitHub providers",
    "status": "IN_PROGRESS",
    "assignedTo": "agent_def456",
    "workspaceId": "default",
    "scope": "Cover login, logout, and session management",
    "acceptanceCriteria": [
      "Users can log in with Google",
      "Users can log in with GitHub",
      "Sessions persist across browser restarts",
      "Logout clears all session data"
    ],
    "dependencies": [],
    "blockers": [],
    "createdAt": "2026-03-03T10:00:00Z",
    "updatedAt": "2026-03-03T11:30:00Z",
    "startedAt": "2026-03-03T10:15:00Z",
    "completedAt": null
  }
}

​
Update Task Status

Update the status of a task: 
routa task update-status [OPTIONS]
Options:
  • --id <ID> - Task ID (required)
  • --status <STATUS> - New status (required): PENDING, IN_PROGRESS, REVIEW_REQUIRED, COMPLETED, NEEDS_FIX, BLOCKED, CANCELLED
  • --agent-id <ID> - Agent ID performing the update (required)
  • --summary <TEXT> - Optional completion summary
Examples: 
# Mark task as in progress
routa task update-status \
  --id task_abc123 \
  --status IN_PROGRESS \
  --agent-id agent_def456

# Mark task as completed with summary
routa task update-status \
  --id task_abc123 \
  --status COMPLETED \
  --agent-id agent_def456 \
  --summary "Implemented OAuth login for Google and GitHub. All tests passing."

# Mark task as needing fixes
routa task update-status \
  --id task_abc123 \
  --status NEEDS_FIX \
  --agent-id agent_gate \
  --summary "Login works but session timeout is too short"
Output: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "taskId": "task_abc123",
    "status": "COMPLETED",
    "updatedAt": "2026-03-03T14:30:00Z",
    "summary": "Implemented OAuth login for Google and GitHub. All tests passing."
  }
}

​
Task Workflows

​
Typical Task Lifecycle

Here’s a typical workflow for a task: 
# 1. Create task
TASK_ID=$(routa task create \
  --title "Add export feature" \
  --objective "Allow users to export data to CSV" \
  --workspace-id project | jq -r '.result.taskId')

echo "Created task: $TASK_ID"

# 2. Assign to agent and mark in progress
AGENT_ID="agent_crafter_001"
routa task update-status \
  --id "$TASK_ID" \
  --status IN_PROGRESS \
  --agent-id "$AGENT_ID"

# 3. Agent completes work, mark for review
routa task update-status \
  --id "$TASK_ID" \
  --status REVIEW_REQUIRED \
  --agent-id "$AGENT_ID" \
  --summary "Export feature implemented with CSV and JSON formats"

# 4. Review and approve
REVIEWER_ID="agent_gate_001"
routa task update-status \
  --id "$TASK_ID" \
  --status COMPLETED \
  --agent-id "$REVIEWER_ID" \
  --summary "Approved: All acceptance criteria met"

​
Handling Task Feedback

When a task needs fixes: 
# Reviewer marks task as needing fixes
routa task update-status \
  --id task_abc123 \
  --status NEEDS_FIX \
  --agent-id agent_gate \
  --summary "Export fails for large datasets. Need pagination."

# Developer fixes and resubmits
routa task update-status \
  --id task_abc123 \
  --status IN_PROGRESS \
  --agent-id agent_crafter

routa task update-status \
  --id task_abc123 \
  --status REVIEW_REQUIRED \
  --agent-id agent_crafter \
  --summary "Added pagination for exports over 1000 rows"

​
Task Dependencies

While the CLI doesn’t have a direct command for setting dependencies, you can manage them through the workspace: 
# Check task details including dependencies
routa task get --id task_abc123 | jq '.result.dependencies'

# Monitor blocked tasks
routa task list --workspace-id project | \
  jq '.result.tasks[] | select(.status == "BLOCKED")'

​
Filtering and Monitoring

Use jq to filter tasks by various criteria: 
# Get all pending tasks
routa task list | jq '.result.tasks[] | select(.status == "PENDING")'

# Get tasks assigned to specific agent
routa task list | jq '.result.tasks[] | select(.assignedTo == "agent_def456")'

# Get completed tasks from today
TODAY=$(date -u +"%Y-%m-%d")
routa task list | jq --arg date "$TODAY" \
  '.result.tasks[] | select(.status == "COMPLETED" and (.completedAt | startswith($date)))'

# Count tasks by status
routa task list | jq '.result.tasks | group_by(.status) | map({status: .[0].status, count: length})'

​
Integration with Agents

Tasks and agents work together: 
# Get agent's current task
AGENT_ID="agent_def456"
CURRENT_TASK=$(routa agent status --id "$AGENT_ID" | jq -r '.result.currentTask')

if [ "$CURRENT_TASK" != "null" ]; then
  echo "Agent is working on:"
  routa task get --id "$CURRENT_TASK" | jq '.result | {title, status, objective}'
else
  echo "Agent is idle"
fi

​
Bulk Operations

Create multiple tasks from a file: 
#!/bin/bash
# tasks.txt format: TITLE|OBJECTIVE

while IFS='|' read -r title objective; do
  routa task create \
    --title "$title" \
    --objective "$objective" \
    --workspace-id project
  echo "Created: $title"
done < tasks.txt

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us