@lumenflow/cli


> Command-line interface for LumenFlow workflow framework

Installation

``bash
npm install @lumenflow/cli
`

Quick Start

`bash


Install the CLI

pnpm add -D @lumenflow/cli # or: npm install -D @lumenflow/cli

Initialize LumenFlow (works with any AI)

pnpm exec lumenflow

Or specify your AI tool for enhanced integration

pnpm exec lumenflow --client claude # Claude Code
pnpm exec lumenflow --client cursor # Cursor
pnpm exec lumenflow --client windsurf # Windsurf
pnpm exec lumenflow --client cline # Cline
pnpm exec lumenflow --client aider # Aider
pnpm exec lumenflow --client all # All integrations
`

The default lumenflow command creates AGENTS.md and LUMENFLOW.md which work with any AI coding assistant. The --client flag adds vendor-specific configuration files for deeper integration.

See AI Integrations for details on each tool.

Overview

This package provides CLI commands for the LumenFlow workflow framework, including:

- WU (Work Unit) management: Claim, complete, block, and track work units
- Memory layer: Session tracking, context recovery, and agent coordination
- Initiative orchestration: Multi-phase project coordination
- Quality gates: Pre-merge validation and checks

Commands




$3

| Command | Description |
| ---------------- | --------------------------------------------- |
| wu-block | Block WU with reason |
| wu-claim | Claim WU and create worktree |
| wu-cleanup | Cleanup after PR merge |
| wu-create | Create new WU spec |
| wu-delete | Delete WU spec and cleanup |
| wu-deps | Show WU dependencies |
| wu-done | Complete WU (merge, stamp, cleanup) from main |
| wu-edit | Edit WU spec fields |
| wu-infer-lane | Infer lane from code paths/description |
| wu-preflight | Pre-flight checks before wu:done |
| wu-prep | Run gates in worktree, prep for wu:done |
| wu-proto | Create WU prototype |
| wu-prune | Clean stale worktrees |
| wu-recover | Analyze and fix WU state inconsistencies |
| wu-release | Release orphaned WU (in_progress to ready) |
| wu-repair | Repair WU state issues |
| wu-spawn | Generate sub-agent spawn prompt |
| wu-status | Show WU status, location, valid commands |
| wu-unblock | Unblock WU |
| wu-unlock-lane | Unlock stuck lane |
| wu-validate | Validate WU spec |

$3

| Command | Description |
| -------------------- | ------------------------------------------ |
| agent-issues-query | Query GitHub issues for agent work |
| agent-log-issue | Log issue during agent session |
| agent-session | Start agent session |
| agent-session-end | End agent session |
| mem-checkpoint | Save progress checkpoint |
| mem-cleanup | Clean up stale memory data |
| mem-context | Get context for current lane/WU |
| mem-create | Create memory node (bug discovery) |
| mem-delete | Delete/archive a memory node |
| mem-export | Export memory as markdown |
| mem-inbox | Check coordination signals |
| mem-init | Initialize memory for WU |
| mem-ready | Check pending memory nodes |
| mem-recover | Generate recovery context after compaction |
| mem-signal | Broadcast coordination signal |
| mem-start | Start a memory session |
| mem-summarize | Summarize memory context |
| mem-triage | Triage discovered bugs |

$3

| Command | Description |
| ---------------------------- | -------------------------------- |
| initiative-add-wu | Add WU to initiative |
| initiative-bulk-assign-wus | Bulk assign WUs to initiative |
| initiative-create | Create new initiative |
| initiative-edit | Edit initiative fields |
| initiative-list | List all initiatives |
| initiative-plan | Link plan to initiative |
| initiative-status | Show initiative status |
| orchestrate-init-status | Compact initiative progress view |
| orchestrate-initiative | Orchestrate initiative execution |
| orchestrate-monitor | Monitor spawn/agent activity |
| spawn-list | List active spawned agents |

$3

| Command | Description |
| ------------------ | ---------------------------- |
| flow-bottlenecks | Identify flow bottlenecks |
| flow-report | Generate flow metrics report |
| metrics | View workflow metrics |
| metrics-snapshot | Capture metrics snapshot |

$3

| Command | Description |
| -------------- | --------------------------- |
| lane-health | Check lane config health |
| lane-suggest | Suggest lane for code paths |

$3

| Command | Description |
| -------------------- | ----------------------------- |
| gates | Run all quality gates |
| lumenflow-gates | Run all quality gates (alias) |
| lumenflow-validate | Run validation checks (alias) |
| validate | Run validation checks |

$3

| Command | Description |
| -------------------------- | ----------------------------------------- |
| backlog-prune | Clean stale backlog entries |
| init-plan | Link plan to initiative (alias) |
| lumenflow | Initialize LumenFlow in a project |
| lumenflow-commands | List all available CLI commands |
| lumenflow-docs-sync | Sync agent docs (for upgrades) (alias) |
| lumenflow-doctor | Diagnose LumenFlow configuration |
| lumenflow-init | Initialize LumenFlow in a project (alias) |
| lumenflow-integrate | Generate enforcement hooks for client |
| lumenflow-metrics | View workflow metrics (alias) |
| lumenflow-release | Run release workflow |
| lumenflow-sync-templates | Sync templates to project |
| lumenflow-upgrade | Upgrade LumenFlow packages |
| plan-create | Create a new plan |
| plan-edit | Edit plan content |
| plan-link | Link plan to WU or initiative |
| plan-promote | Promote plan to WU |
| signal-cleanup | Clean up stale signals |
| state-bootstrap | Bootstrap state store |
| state-cleanup | Clean up stale state data |
| state-doctor | Diagnose state store issues |
| sync-templates | Sync templates to project (alias) |

$3

| Command | Description |
| ------------- | -------------------------------- |
| file-delete | Delete file with audit trail |
| file-edit | Edit file with audit trail |
| file-read | Read file with audit trail |
| file-write | Write file with audit trail |
| git-branch | Show git branch with audit trail |
| git-diff | Show git diff with audit trail |
| git-log | Show git log with audit trail |
| git-status | Show git status with audit trail |

Usage

Commands are typically invoked via pnpm scripts in your project:

`bash


WU workflow

pnpm wu:claim --id WU-123 --lane operations
pnpm wu:done --id WU-123

Memory operations

pnpm mem:checkpoint "Completed port definitions" --wu WU-123
pnpm mem:inbox --since 10m

Initiative management

pnpm initiative:status INIT-007

Quality gates

pnpm gates
`

$3

`bash


After installing the package


npx wu-claim --id WU-123 --lane operations
npx gates
`

Global Flags

All commands support these flags:

| Flag | Description |
| ----------------- | ------------------------- |
| --help, -h | Show help for the command |
| --version, -V | Show version number |
| --no-color | Disable colored output |

Environment Variables

| Variable | Description |
| ------------- | -------------------------------------------------------------------------------------- |
| NO_COLOR | Disable colored output when set (any value, per no-color.org) |
| FORCE_COLOR | Override color level: 0 (disabled), 1 (basic), 2 (256 colors), 3 (16m colors) |

Integration

The CLI integrates with other LumenFlow packages:

- @lumenflow/core - Git operations, worktree management
- @lumenflow/memory - Session and context persistence
- @lumenflow/agent - Agent session management
- @lumenflow/initiatives - Initiative tracking

MCP Server Setup (Claude Code)

LumenFlow provides an MCP (Model Context Protocol) server for deep integration with Claude Code.

When you run lumenflow init --client claude, a .mcp.json is automatically created:

`json
{
"mcpServers": {
"lumenflow": {
"command": "npx",
"args": ["@lumenflow/mcp"]
}
}
}
`

The @lumenflow/mcp server provides tools for WU lifecycle, memory coordination, and lane management directly within Claude Code.

See AI Integrations for full MCP documentation.

Documentation

For complete documentation, see lumenflow.dev.

Upgrading

To upgrade LumenFlow packages:

`bash


Check for available updates

pnpm outdated @lumenflow/*

Update all LumenFlow packages

pnpm update @lumenflow/cli @lumenflow/core @lumenflow/memory @lumenflow/agent @lumenflow/initiatives

Sync documentation and templates

pnpm exec lumenflow docs:sync
`

Important: Always run docs:sync` after upgrading to update agent onboarding documentation, workflow rules, and vendor-specific configurations.

For detailed upgrade instructions, migration guides, and troubleshooting, see UPGRADING.md.

License

Apache-2.0