@lumenflow/cli

Command-line interface for LumenFlow workflow framework

Installation

npm install @lumenflow/cli

Quick Start

# 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

Work Unit Management

| Command | Description | | ---------------- | ------------------------------------------------------------- | | wu-block | Block WU with reason | | wu-brief | Generate handoff prompt for sub-agent WU execution | | wu-claim | Claim WU and create worktree | | wu-cleanup | Cleanup after PR merge | | wu-create | Create new WU spec | | wu-delegate | Generate delegation prompt and record explicit lineage intent | | 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-status | Show WU status, location, valid commands | | wu-unblock | Unblock WU | | wu-unlock-lane | Unlock stuck lane | | wu-validate | Validate WU spec |

Memory & Session

| 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 |

Initiative Orchestration

| 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 |

Metrics & Analytics

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

Lane Tooling

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

Verification & Gates

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

System & Setup

| 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) |

File & Git Operations

| 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:

# 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

Direct CLI Usage

# 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:

{
  "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:

# 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