FlowState CLI

Command-line interface for Epic FlowState with dynamic collection support.

Installation

npm install -g @epic-flow/flowstate-cli
# or
yarn global add @epic-flow/flowstate-cli

Quick Start

# Initialize a new project
flowstate init

# Add a server profile
flowstate server add production --url https://api.flowstate.dev --domain prod

# Authenticate
flowstate login
# Enter your email when prompted
# Enter the verification code sent to your email

# Work with any collection
flowstate collection tasks list
flowstate collection workspaces create --interactive
flowstate collection projects get proj_123

Commands

Project Initialization

flowstate init [options]

Initialize a new FlowState project with optional integrations.

Server Management

Manage server profiles stored in ~/.flowstate/config.json.

# Add a new server profile
flowstate server add <name> --url <url> --domain <domainId>
flowstate server add production --url https://api.flowstate.dev --domain prod

# List all server profiles
flowstate server list
#   NAME            URL                         DOMAIN          AUTH
# * flowstate-dev   https://localhost:7443      flowstate-dev   ✓ [email protected]
#   production      https://api.flowstate.dev   prod            ✗ Not logged in

# Switch active server
flowstate server use <name>
flowstate server use production

# Remove a server profile
flowstate server remove <name>

# Test server connection
flowstate server test [name]   # Tests active server if name omitted

Authentication

Login using email + verification code (same as web app).

# Login to active server
flowstate login
# > Enter your email: [email protected]
# > Verification code sent! Check your email.
# > Enter code: 123456
# ✓ Logged in as [email protected]

# Login to specific server profile
flowstate login --profile production

# Check auth status
flowstate auth
# Server: flowstate-dev
# User: [email protected]
# Token expires: in 14 minutes

# Logout from active server
flowstate logout

# Logout from specific server
flowstate logout --profile production

# Logout from all servers
flowstate logout --all

Collection Operations

Work with any collection in the database using a unified command structure.

Available Collections

All collections from @epic-flow/collections are automatically available:

• tasks
• projects
• milestones
• workspaces
• codebases
• users
• discussions
• approvals
• templates
• documents
• timeentries
• And more...

Create

# JSON data
flowstate collection <name> create --data '{"field":"value",...}'

# From file
flowstate collection <name> create --file data.json

# Interactive mode
flowstate collection <name> create --interactive

List

# All documents
flowstate collection <name> list

# With filter
flowstate collection <name> list --filter "status=active,completed=false"

# JSON filter with operators
flowstate collection <name> list --filter '{"status":{"$in":["To Do","In Progress"]}}'

# With sorting and pagination
flowstate collection <name> list --sort "createdAt:desc" --limit 20 --skip 10

# Different output formats
flowstate collection <name> list --format table   # Default: ASCII table
flowstate collection <name> list --format json    # JSON for scripting
flowstate collection <name> list --format csv     # CSV for spreadsheets

Get

# Get by ID
flowstate collection <name> get <id>

# YAML format
flowstate collection <name> get <id> --format yaml

Update

# Set specific fields
flowstate collection <name> update <id> --set field=value --set other=value

# JSON data
flowstate collection <name> update <id> --data '{"field":"newvalue"}'

# Interactive mode
flowstate collection <name> update <id> --interactive

Delete

# With confirmation
flowstate collection <name> delete <id>

# Skip confirmation
flowstate collection <name> delete <id> --force

Query

# Advanced RxDB queries
flowstate collection <name> query '{"field":{"$operator":"value"}}'

# Example: Find all active tasks due before a date
flowstate collection tasks query '{
  "status": {"$in": ["To Do", "In Progress"]},
  "dueAt": {"$lt": "2025-10-31"},
  "completed": false
}'

Examples

Task Management

# Create a task
flowstate collection tasks create --data '{
  "name": "implement-feature",
  "title": "Implement New Feature",
  "description": "Add dynamic CLI support",
  "status": "To Do",
  "type": "todo",
  "completed": false,
  "projectId": "proj_123",
  "milestoneId": "mil_456",
  "trashed": false
}'

# List in-progress tasks
flowstate collection tasks list --filter "status=In Progress" --format table

# Update task status
flowstate collection tasks update task_789 --set status="Complete" --set completed=true

# Delete completed tasks
flowstate collection tasks list --filter "completed=true" --format json | \
  jq -r '.[].id' | \
  xargs -I {} flowstate collection tasks delete {} --force

Workspace Management

# Create workspace interactively
flowstate collection workspaces create --interactive

# List active workspaces
flowstate collection workspaces list --filter "status=active"

# View workspace details
flowstate collection workspaces get wks_abc123

# Archive workspace
flowstate collection workspaces update wks_abc123 --set status="archived"

Project Management

# List all projects
flowstate collection projects list

# Find projects by organization
flowstate collection projects query '{"orgId":"org_123","status":"active"}'

# Export projects to CSV
flowstate collection projects list --format csv > projects.csv

Configuration

Global configuration is stored in ~/.flowstate/config.json. This config is shared between CLI and MCP server.

{
  "version": "1.0.0",
  "activeServerId": "flowstate-dev",
  "servers": {
    "flowstate-dev": {
      "id": "flowstate-dev",
      "name": "FlowState Dev",
      "url": "https://localhost:7443",
      "domainId": "flowstate-dev",
      "auth": {
        "accessToken": "eyJhbG...",
        "refreshToken": "eyJhbG...",
        "expiresAt": 1768412132000,
        "userId": "user_abc123",
        "email": "[email protected]"
      }
    },
    "production": {
      "id": "production",
      "name": "Production",
      "url": "https://api.flowstate.dev",
      "domainId": "prod",
      "auth": null
    }
  }
}

Config Fields

| Field | Description | |-------|-------------| | activeServerId | Currently active server profile | | servers.<id>.url | Server URL | | servers.<id>.domainId | Domain ID for multi-tenant isolation | | servers.<id>.auth | Auth tokens (set via flowstate login) | | servers.<id>.auth.expiresAt | Token expiration timestamp (ms) |

MCP Server Configuration

The MCP server can use the shared config via --profile flag:

{
  "mcpServers": {
    "flowstate": {
      "command": "npx",
      "args": ["@epicdm/flowstate-mcp", "--profile", "flowstate-dev"]
    }
  }
}

Or use environment variables:

RXDB_SERVER_URL=http://localhost:7080
AUTH_TOKEN=your-token
DOMAIN_ID=your-domain

Filter Syntax

Simple Filters

Key=value pairs separated by commas:

--filter "status=active,completed=false"

JSON Filters

Full RxDB query syntax:

# Exact match
--filter '{"status":"active"}'

# Operators
--filter '{"count":{"$gt":10}}'
--filter '{"status":{"$in":["To Do","In Progress"]}}'
--filter '{"name":{"$regex":"test.*"}}'

# Array match
--filter '{"tagIds":{"$elemMatch":"priority:high"}}'

# Combined
--filter '{"status":"active","createdAt":{"$gt":"2025-01-01"}}'

Scripting

The CLI is designed for automation:

#!/bin/bash

# Get all active tasks and update their status
flowstate collection tasks list --filter "status=To Do" --format json | \
  jq -r '.[].id' | \
  while read task_id; do
    flowstate collection tasks update "$task_id" --set status="In Progress"
  done

# Export weekly report
START_DATE=$(date -d "7 days ago" +%Y-%m-%d)
flowstate collection tasks query "{\"completedAt\":{\"\$gte\":\"$START_DATE\"}}" \
  --format csv > weekly-completed-tasks.csv

Development

# Install dependencies
yarn install

# Build
yarn build

# Run tests
yarn test

# Run locally
node dist/cli.js --help

Architecture

The CLI uses runtime reflection to auto-discover collections from @epic-flow/collections:

• CommandRegistry: Discovers collections on startup
• CollectionManager: Provides generic CRUD operations
• QueryBuilder: Parses filter syntax to RxDB queries
• OutputFormatter: Formats results as table/JSON/CSV
• InteractivePrompts: Schema-driven interactive input

Adding a new collection to @epic-flow/collections automatically makes it available in the CLI.

TODO Scanner

Scan project for TODO comments and sync with FlowState tasks:

# Scan entire project
flowstate scan-todos

# Dry run (preview without changes)
flowstate scan-todos --dry-run

# Scan specific file
flowstate scan-todos --file src/components/Auth.tsx

# Generate summary only (no sync)
flowstate scan-todos --summary-only

# Verbose output
flowstate scan-todos --verbose

How It Works

1. Scans source files for TODO comments
2. Creates tasks for new TODOs without taskId
3. Syncs existing TODOs with tasks using timestamps
4. Updates comments with task metadata
5. Generates summary files

Comment Format

// TODO: Fix authentication bug
// After sync: // TODO: [task_abc123|To Do:2025-10-24T15:30:00.000Z] Fix authentication bug

Optional Git Hook

Install automatic scanning after commits:

flowstate scan-todos install-hook todo-scan

File Mapping System

Track file-to-entity relationships without modifying source files.

The File Mapping System stores associations between source files and FlowState entities (tasks, documents, specs) in .flowstate/mappings/ JSON files instead of embedding metadata in your source code.

Key Benefits

• Clean git diffs - No embedded metadata pollution in source files
• Zero merge conflicts - No competing metadata changes
• Bidirectional lookups - Find files by ID or IDs by file
• Content hashing - Automatic change detection
• Team-shareable - Mapping files committed to git

Quick Start

# Scan TODOs with mapping system (read-only mode)
flowstate scan-todos --use-mapping-system

# Migrate existing embedded IDs to mappings
flowstate migrate-mappings --dry-run  # Preview first
flowstate migrate-mappings             # Perform migration

# Query mappings
flowstate mappings list --file src/api.ts
flowstate mappings list --task task_abc123
flowstate mappings list                # Show summary

How It Works

Traditional approach (embedded IDs):

// TODO: [task_abc123|To Do:2025-11-02] Implement retry logic

With mapping system:

// TODO: Implement retry logic

The association is stored in .flowstate/mappings/todos.json:

{
  "src/api.ts:42": {
    "taskId": "task_abc123",
    "text": "Implement retry logic",
    "status": "active"
  }
}

File Structure

.flowstate/
└── mappings/
    ├── todos.json       # TODO → Task mappings
    ├── markdown.json    # Markdown → Document mappings
    ├── files.json       # Code → Spec mappings
    └── commits.json     # Commit → Task mappings

Migration Guide

Migrate existing embedded IDs to mapping system:

# Preview migration (safe, read-only)
flowstate migrate-mappings --dry-run

# Migrate everything
flowstate migrate-mappings

# Migrate specific type only
flowstate migrate-mappings --type todos
flowstate migrate-mappings --type markdown

Important: Migration never modifies source files. It only extracts IDs and creates mappings.

Commands

List mappings:

# Show all mappings
flowstate mappings list

# Show mappings for specific file
flowstate mappings list --file src/api.ts

# Find files for task
flowstate mappings list --task task_abc123

# Find files for document
flowstate mappings list --document steering_arch_001

# List by type
flowstate mappings list --type todos

Scan with mapping system:

# Use mapping system (recommended)
flowstate scan-todos --use-mapping-system

# Preview first
flowstate scan-todos --use-mapping-system --dry-run

# Specific file
flowstate scan-todos --use-mapping-system --file src/api.ts

Documentation

For comprehensive documentation, see:

• File Mapping System Guide - Complete documentation
• Migration Example - Sample migration output

Observability Platform

FlowState CLI includes a comprehensive observability platform for monitoring errors, logs, and user sessions across your applications.

Features

• Error Tracking - Capture and analyze errors with stack traces and source maps
• Log Management - Centralized logging with filtering and search
• Session Tracking - User session monitoring with breadcrumbs
• Real-time Streaming - Live event monitoring with SSE
• AI-Enhanced Debugging - Pattern detection and fix suggestions
• Task Integration - Automatic task creation from errors
• Context Tracking - Session context for all CLI operations

Quick Start

Initialize observability during project setup:

flowstate init
# Answer yes to "Set up observability platform?"

Or configure manually:

flowstate obs config set server-url http://localhost:7081
flowstate obs config set api-key your-api-key
flowstate obs config set default-project my-project

Commands

Error Management

# List errors
flowstate obs errors list --level fatal

# View error details
flowstate obs errors view error-123

# View statistics
flowstate obs errors stats --time-range 7d

# Create task from error
flowstate obs errors view error-123 --create-task

Log Management

# List logs
flowstate obs logs list --level error

# Search logs
flowstate obs logs list --search "database error"

# View log details
flowstate obs logs view log-456

Session Management

# List sessions
flowstate obs sessions list

# View session details with breadcrumbs
flowstate obs sessions view session-abc123

Real-Time Streaming

# Stream all events
flowstate obs tail

# Stream only errors
flowstate obs tail --type error

# Stream fatal errors
flowstate obs tail --type error --level fatal

# Stream specific session
flowstate obs tail --session session-123

Configuration

# Show configuration
flowstate obs config show

# Get specific setting
flowstate obs config get session-tracking

# Set configuration
flowstate obs config set auto-link true
flowstate obs config set session-tracking true

# Reset to defaults
flowstate obs config reset

Configuration Options

| Setting | Default | Description | |---------|---------|-------------| | enabled | false | Master switch for observability | | serverUrl | - | Observability server URL | | apiKey | - | Authentication API key | | defaultProject | - | Default project for commands | | autoLink | false | Auto-link errors to tasks | | sessionTracking | false | Track session context | | autoCreateTasks | false | Auto-create tasks from errors |

Task Creation from Errors

Automatically create FlowState tasks from errors with AI-generated fix suggestions:

flowstate obs errors view error-123 --create-task

Features:

• 9 error pattern types detected
• Priority assignment (critical/high/medium/low)
• 3-5 fix suggestions per pattern
• Full error context and breadcrumbs
• Automatic task linking

Session Context Tracking

Enable session tracking to automatically capture context during all CLI operations:

flowstate obs config set session-tracking true

Tracked Context:

• User ID
• Task ID
• Project ID
• Git branch
• Working directory
• Workspace ID
• Codebase ID

Documentation

• OBSERVABILITY_CLI.md - Complete command reference
• USAGE_EXAMPLES_OBS.md - Practical usage examples and workflows

License

MIT