---
title: "Workflow Commands"
description: "Complete reference for TraceRTM CLI workflow management commands"
keywords: [cli, workflows, status, transitions, approval, commands]
---

# Workflow Commands

Manage workflows, status transitions, and approval processes from the command line.

## List Workflows

### Basic Usage

```bash
# List all workflows
trace workflow list

# List workflows in project
trace workflow list --project proj_abc123
```

### Filter by Type

```bash
# Filter by workflow type
trace workflow list --type requirement_workflow
```

### Output Formats

```bash
# Table (default)
trace workflow list

# JSON
trace workflow list --output json

# YAML
trace workflow list --output yaml
```

---

## Get Workflow

### By ID

```bash
trace workflow get wf_abc123
```

### With Details

```bash
# Include states and transitions
trace workflow get wf_abc123 --include states,transitions

# Include all details
trace workflow get wf_abc123 --include all
```

### Output

```bash
# JSON output
trace workflow get wf_abc123 --output json | jq

# View states
trace workflow get wf_abc123 --output json | jq '.states'

# View transitions
trace workflow get wf_abc123 --output json | jq '.transitions'
```

---

## Create Workflow

### Basic Creation

```bash
trace workflow create \
  --name "Requirement Workflow" \
  --project proj_abc123
```

### With States

```bash
trace workflow create \
  --name "Custom Workflow" \
  --project proj_abc123 \
  --states '[
    {"name": "draft", "category": "initial"},
    {"name": "in_review", "category": "in_progress"},
    {"name": "approved", "category": "done"}
  ]'
```

### With Transitions

```bash
trace workflow create \
  --name "Requirement Workflow" \
  --project proj_abc123 \
  --transitions '[
    {"from": "draft", "to": "in_review", "name": "submit"},
    {"from": "in_review", "to": "approved", "name": "approve"},
    {"from": "in_review", "to": "draft", "name": "reject"}
  ]'
```

### Complete Example

```bash
trace workflow create \
  --name "Safety-Critical Workflow" \
  --project proj_abc123 \
  --description "Workflow for safety-critical requirements" \
  --states '[
    {"name": "draft", "category": "initial"},
    {"name": "review", "category": "in_progress"},
    {"name": "safety_review", "category": "in_progress"},
    {"name": "approved", "category": "done"},
    {"name": "rejected", "category": "done"}
  ]' \
  --transitions '[
    {"from": "draft", "to": "review", "name": "submit_for_review"},
    {"from": "review", "to": "safety_review", "name": "approve_technical"},
    {"from": "safety_review", "to": "approved", "name": "approve_safety"},
    {"from": "review", "to": "rejected", "name": "reject"},
    {"from": "safety_review", "to": "rejected", "name": "reject"}
  ]' \
  --output json
```

---

## Update Workflow

### Update Name

```bash
trace workflow update wf_abc123 \
  --name "Updated Workflow Name"
```

### Update Description

```bash
trace workflow update wf_abc123 \
  --description "Updated workflow description"
```

### Add State

```bash
trace workflow update wf_abc123 \
  --add-state '{"name": "on_hold", "category": "in_progress"}'
```

### Add Transition

```bash
trace workflow update wf_abc123 \
  --add-transition '{"from": "draft", "to": "on_hold", "name": "hold"}'
```

### Remove State

```bash
trace workflow update wf_abc123 \
  --remove-state "deprecated"
```

---

## Delete Workflow

### Delete by ID

```bash
trace workflow delete wf_abc123
```

### Force Delete

```bash
# Skip confirmation
trace workflow delete wf_abc123 --force
```

---

## Item Transitions

### Get Available Transitions

```bash
# List available transitions for an item
trace workflow transitions item_req_001
```

Output:
```
Available transitions:
  - submit_for_review (draft -> in_review)
  - approve (in_review -> approved)
  - reject (in_review -> draft)
```

### Transition Item

```bash
# Simple transition
trace workflow transition item_req_001 \
  --transition submit_for_review

# With comment
trace workflow transition item_req_001 \
  --transition approve \
  --comment "Approved by tech lead after review"
```

### Approve Item

```bash
# Approve item
trace workflow approve item_req_001 \
  --comment "Approved for implementation"
```

### Reject Item

```bash
# Reject item (requires comment)
trace workflow reject item_req_001 \
  --comment "Needs more detail on security requirements"
```

---

## Workflow Status

### Get Item Status

```bash
# Get current status
trace workflow status item_req_001
```

### Get Status History

```bash
# Get status change history
trace workflow history item_req_001
```

Output:
```
Status History:
  2024-12-08 10:30:00 - draft -> in_review (submit_for_review) by user_123
  2024-12-08 14:15:00 - in_review -> approved (approve) by user_456
```

---

## Examples

### Create and Apply Workflow

```bash
#!/bin/bash

# Create workflow
WF_ID=$(trace workflow create \
    --name "Standard Workflow" \
    --project proj_123 \
    --output json | jq -r '.id')

# Apply to items
ITEMS=$(trace item list --project proj_123 --output json | jq -r '.[] | .id')

echo "$ITEMS" | while read -r item_id; do
    trace item update "$item_id" --workflow "$WF_ID"
done
```

### Batch Status Transition

```bash
#!/bin/bash

# Get all items in review
ITEMS=$(trace item list \
    --project proj_123 \
    --status in_review \
    --output json | jq -r '.[] | .id')

# Approve all
echo "$ITEMS" | while read -r item_id; do
    trace workflow approve "$item_id" \
        --comment "Batch approved for release"
done
```

### Workflow Validation

```bash
#!/bin/bash

# Check for items stuck in workflow
STUCK=$(trace item list \
    --project proj_123 \
    --status in_review \
    --updated-before "$(date -d '7 days ago' -Iseconds)" \
    --output json)

if [ "$(echo "$STUCK" | jq 'length')" -gt 0 ]; then
    echo "Found stuck items:"
    echo "$STUCK" | jq -r '.[] | "\(.id): \(.title)"'
fi
```

---

## Related Documentation

- [CLI Commands](./03-commands) - All CLI commands
- [Item Commands](./03b-item-commands) - Item management
- [Workflows API](/docs/api-reference/rest-api/endpoints/workflows) - REST API reference
