@uncaged/cli-workflow

uwf CLI — thread lifecycle, workflow registry, CAS inspection, and setup.

Overview

Layer 4 entry point for the workflow engine. The uwf binary orchestrates one step per invocation: load thread head from threads.yaml, run the moderator, spawn the configured agent CLI, run extract, append a CAS step node, and update the head pointer (or archive when $END).

Four-Layer Architecture

workflow → thread → step → turn
模板定义   执行实例   单步结果   agent内部交互

• Workflow (layer 1): YAML template with roles and routing graph
• Thread (layer 2): Single workflow execution instance
• Step (layer 3): One moderator→agent→extract cycle
• Turn (layer 4): Agent-internal interactions (use step show or CAS to inspect)

This package has no library src/index.ts — it is consumed as a CLI binary only.

Dependencies: @uncaged/json-cas, @uncaged/json-cas-fs, @uncaged/workflow-util-agent, @uncaged/workflow-protocol, @uncaged/workflow-util, commander, dotenv, mustache, yaml

Installation

Included as the uwf binary when you install @uncaged/cli-workflow:

bun add -g @uncaged/cli-workflow
# or from the monorepo:
bun link packages/cli-workflow

CLI Usage

Global options

-V, --version          Show version
--format <json|yaml>   Output format (default: json)
-h, --help             Show help

Thread (Layer 2: Execution Instances)

| Command | Description | |---------|-------------| | uwf thread start <workflow> -p <prompt> | Create a thread without executing | | uwf thread exec <thread-id> [--agent <cmd>] [-c <count>] [--background] | Execute one or more moderator→agent→extract cycles | | uwf thread show <thread-id> | Show thread head pointer | | uwf thread list [--status <status>] [--after <date>] [--before <date>] [--skip <n>] [--take <n>] | List threads filtered by status (idle, running, completed, active, or comma-separated), time range (ISO or relative like '7d'), with pagination | | uwf thread read <thread-id> [--quota N] [--before <hash>] [--start] | Render thread as readable markdown |

thread read, step list, and step show work on both active and completed threads. | uwf thread stop <thread-id> | Stop background execution (keep thread active) | | uwf thread cancel <thread-id> | Cancel thread (stop + archive to history) |

Examples:

uwf thread start solve-issue -p "Fix the login redirect bug"
uwf thread exec 01ARZ3NDEKTSV4RRFFQ69G5FAV
uwf thread exec 01ARZ3NDEKTSV4RRFFQ69G5FAV -c 3 --agent uwf-builtin
uwf thread exec 01ARZ3NDEKTSV4RRFFQ69G5FAV --background
uwf thread list --status running
uwf thread list --status active
uwf thread list --status idle,completed
uwf thread list --after 7d --take 10
uwf thread read 01ARZ3NDEKTSV4RRFFQ69G5FAV --quota 8000
uwf thread stop 01ARZ3NDEKTSV4RRFFQ69G5FAV

Step (Layer 3: Single Cycle Results)

| Command | Description | |---------|-------------| | uwf step list <thread-id> | List all steps in a thread chronologically | | uwf step show <step-hash> | Show step metadata and frontmatter | | uwf step read <step-hash> [--quota <chars>] | Read a step's turns as human-readable markdown | | uwf step fork <step-hash> | Fork a thread from a specific step |

Examples:

uwf step list 01ARZ3NDEKTSV4RRFFQ69G5FAV
uwf step show 32GCDE899RRQ3
uwf step read 32GCDE899RRQ3 --quota 2000
uwf step fork 32GCDE899RRQ3

Workflow (Layer 1: Templates)

| Command | Description | |---------|-------------| | uwf workflow add <file.yaml> | Register a workflow from YAML | | uwf workflow show <name-or-hash> | Show workflow definition | | uwf workflow list | List registered workflows |

CAS

| Command | Description | |---------|-------------| | uwf cas get <hash> [--timestamp] | Read a CAS node | | uwf cas put <type-hash> <data> | Store a node, print hash | | uwf cas put-text <text> | Store plain text, print hash | | uwf cas has <hash> | Check existence | | uwf cas refs <hash> | List direct references | | uwf cas walk <hash> | Recursive traversal | | uwf cas reindex | Rebuild type index | | uwf cas schema list | List registered schemas | | uwf cas schema get <hash> | Show a schema |

Setup

uwf setup
uwf setup --provider openai --base-url https://api.openai.com/v1 \
  --api-key sk-... --model gpt-4o --agent hermes

Config: ~/.uncaged/workflow/config.yaml (includes API keys).

Skill

| Command | Description | |---------|-------------| | uwf skill cli | Print markdown reference of all uwf commands (for agent skills) |

Log

| Command | Description | |---------|-------------| | uwf log list | List log files with sizes | | uwf log show [--thread <id>] [--process <pid>] [--date YYYY-MM-DD] | Show filtered log entries | | uwf log clean [--before YYYY-MM-DD] | Delete old log files |

Migration Guide

Breaking Changes (v0.x → v1.x)

The CLI was reorganized to clarify the four-layer architecture. No backward compatibility — old commands have been removed.

Renamed Commands

| Old Command | New Command | Notes | |------------|-------------|-------| | workflow put | workflow add | More intuitive verb | | thread step | thread exec | Eliminates ambiguity with "step" noun | | thread list --all | thread list --status completed | Unified status filtering |

Removed Commands (Merged)

| Old Command | New Command | Notes | |------------|-------------|-------| | thread running | thread list --status running | Merged into unified list |

Removed Commands (Split)

| Old Command | New Commands | Notes | |------------|-------------|-------| | thread kill | thread stop or thread cancel | stop keeps thread active, cancel archives it |

Moved Commands

| Old Command | New Command | Notes | |------------|-------------|-------| | thread steps | step list | Moved to step layer | | thread step-details | step show | Moved to step layer | | thread fork | step fork | Moved to step layer (forks are step-based) |

Deprecation Errors

Old commands now show helpful error messages:

$ uwf thread step 01ARZ3NDEKTSV4RRFFQ69G5FAV
Error: Command 'thread step' has been removed.
Use 'thread exec' instead.

For more information, see: uwf help thread exec

Internal Structure

src/
├── cli.ts              Commander entrypoint, command registration
├── format.ts           JSON/YAML output formatting
├── store.ts            CAS store + registry initialization
├── validate.ts         Workflow YAML validation
├── schemas.ts          CLI-local schema registration
├── moderator/          Status-based graph evaluator (next role or $END)
└── commands/
    ├── thread.ts       Thread lifecycle and exec
    ├── step.ts         Step operations (list/show/read/fork)
    ├── workflow.ts     Workflow registry (add/show/list)
    ├── cas.ts          CAS inspection and schema ops
    ├── setup.ts        Interactive/non-interactive setup
    ├── skill.ts        Built-in skill references
    └── log.ts          Process debug log management

Configuration

| File | Purpose | |------|---------| | ~/.uncaged/workflow/config.yaml | Providers, models, default agent | | ~/.uncaged/workflow/.env | API keys (referenced by apiKeyEnv in config) | | ~/.uncaged/workflow/registry.yaml | Workflow name → CAS hash | | ~/.uncaged/workflow/threads.yaml | Active thread head pointers | | ~/.uncaged/workflow/cas/ | Content-addressed node storage |