xiaoju
7b50969307
Implement comprehensive CLI refactoring to clarify the four-layer model: workflow → thread → step → turn ## Breaking Changes ### Renamed Commands - `uwf workflow put` → `uwf workflow add` - `uwf thread step` → `uwf thread exec` ### Removed Commands - `uwf thread running` (merged into `thread list --status running`) - `uwf thread kill` (split into `thread stop` and `thread cancel`) ### Moved Commands - `uwf thread steps` → `uwf step list` - `uwf thread step-details` → `uwf step show` - `uwf thread fork` → `uwf step fork` ## New Commands ### Thread Commands - `uwf thread list --status <idle|running|completed>` - Filter threads by status - `uwf thread stop <thread-id>` - Stop background execution (keep thread active) - `uwf thread cancel <thread-id>` - Cancel thread (stop + archive to history) ### Step Command Group (New) - `uwf step list <thread-id>` - List all steps in a thread - `uwf step show <step-hash>` - Show step details - `uwf step read <step-hash> [--before N]` - Read step output as markdown - `uwf step fork <step-hash>` - Fork thread from a step ## Implementation Details ### Files Modified - `packages/cli-workflow/src/commands/workflow.ts` - Renamed cmdWorkflowPut → cmdWorkflowAdd - `packages/cli-workflow/src/commands/thread.ts`: - Renamed cmdThreadStep → cmdThreadExec - Added cmdThreadStop and cmdThreadCancel (split from cmdThreadKill) - Updated cmdThreadList to support --status filter with idle/running/completed - Removed cmdThreadSteps, cmdThreadStepDetails, cmdThreadFork - `packages/cli-workflow/src/commands/step.ts` - New module with: - cmdStepList (moved from cmdThreadSteps) - cmdStepShow (moved from cmdThreadStepDetails) - cmdStepFork (moved from cmdThreadFork) - cmdStepRead (new, stub implementation pending #462) - `packages/cli-workflow/src/cli.ts` - Updated all CLI command registrations ### Tests Updated - `packages/cli-workflow/src/__tests__/thread-step-count.test.ts` - Updated references from "thread step" to "thread exec" - `packages/cli-workflow/src/__tests__/thread.test.ts` - Updated imports to use cmdStepShow from step.ts ## Test Results All 124 tests pass in cli-workflow package. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@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).
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-agent-kit, @uncaged/workflow-moderator, @uncaged/workflow-protocol, @uncaged/workflow-util, commander, dotenv, 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
| Command | Description |
|---|---|
uwf thread start <workflow> -p <prompt> |
Create a thread without executing |
uwf thread step <thread-id> [--agent <cmd>] [-c <count>] |
Execute one or more moderator→agent→extract cycles |
uwf thread show <thread-id> |
Show thread head pointer |
uwf thread list [--all] |
List active threads (--all includes archived) |
uwf thread steps <thread-id> |
List all steps chronologically |
uwf thread read <thread-id> [--quota N] [--before <hash>] [--start] |
Render thread as readable markdown |
uwf thread fork <step-hash> |
Fork from a specific step |
uwf thread step-details <step-hash> |
Dump full detail node as YAML |
uwf thread kill <thread-id> |
Terminate and archive |
Examples:
uwf thread start solve-issue -p "Fix the login redirect bug"
uwf thread step 01ARZ3NDEKTSV4RRFFQ69G5FAV
uwf thread step 01ARZ3NDEKTSV4RRFFQ69G5FAV -c 3 --agent uwf-builtin
uwf thread read 01ARZ3NDEKTSV4RRFFQ69G5FAV --quota 8000
Workflow
| Command | Description |
|---|---|
uwf workflow put <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. API keys: ~/.uncaged/workflow/.env.
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 |
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
└── commands/
├── thread.ts Thread lifecycle and step execution
├── workflow.ts Workflow registry (put/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 |