Skip to content

CLI Commands

Jump to bottom
github-actions[bot] edited this page Dec 2, 2025 · 9 revisions

CLI Commands

Complete reference for all Sylphx Flow CLI commands.

🛠️ Command Structure

npx @sylphx/flow <command> [subcommand] [options]

📋 Core Commands

flow init - Initialize Project

Initialize your project with Sylphx Flow development agents, MCP tools, hooks, and output styles.

Syntax

npx @sylphx/flow init [options]

Options

  • --target <type> - Force specific target (opencode, claude-code, default: auto-detect)
  • --dry-run - Show what would be done without making changes
  • --skip-agents - Skip agent installation
  • --skip-hooks - Skip git hooks installation
  • --skip-mcp - Skip MCP configuration
  • --skip-output-styles - Skip output styles installation

Examples

# Full initialization (default)
npx @sylphx/flow init

# Preview changes
npx @sylphx/flow init --dry-run

# Initialize without MCP
npx @sylphx/flow init --skip-mcp

# Initialize only agents
npx @sylphx/flow init --skip-hooks --skip-mcp --skip-output-styles

# Force Claude Code target
npx @sylphx/flow init --target claude-code

What Gets Installed

  • Agents: orchestrator, coder, reviewer, writer
  • Hooks: Session and message hooks for system info
  • MCP Configuration: Auto-configured for detected AI tool
  • Output Styles: AI response formatting styles

flow knowledge - Knowledge Base Management

Access and search curated development guidelines and best practices.

Syntax

npx @sylphx/flow knowledge [subcommand] [options]

Subcommands

knowledge search - Search Knowledge Base
npx @sylphx/flow knowledge search <query> [options]

Arguments:

  • query - Search query (required)

Options:

  • --limit <number> - Maximum results to return (default: 5)
  • --include-content - Include full content in results
  • --output <format> - Output format: markdown, json (default: markdown)

Examples:

# Basic search
npx @sylphx/flow knowledge search "react hooks patterns"

# Search with more results
npx @sylphx/flow knowledge search "nextjs routing" --limit 10

# Include full content
npx @sylphx/flow knowledge search "security practices" --include-content

# JSON output
npx @sylphx/flow knowledge search "testing strategies" --output json
knowledge get - Get Specific Document
npx @sylphx/flow knowledge get <uri>

Arguments:

  • uri - Document URI (e.g., "/stacks/react-app")

Examples:

# Get React patterns
npx @sylphx/flow knowledge get "/stacks/react-app"

# Get security guidelines
npx @sylphx/flow knowledge get "/universal/security"

# Get SaaS architecture guide
npx @sylphx/flow knowledge get "/guides/saas-template"
knowledge list - List All Resources
npx @sylphx/flow knowledge list [options]

Options:

  • --category <name> - Filter by category (stacks, guides, universal, data)
  • --output <format> - Output format: markdown, json

Examples:

# List all knowledge
npx @sylphx/flow knowledge list

# List only stacks
npx @sylphx/flow knowledge list --category stacks

# JSON output
npx @sylphx/flow knowledge list --output json
knowledge status - Check Knowledge Base Status
npx @sylphx/flow knowledge status

Shows:

  • Index status
  • Number of documents
  • Number of embeddings
  • Database size
  • Last indexed time

flow codebase - Codebase Search & Indexing

Semantic search across your project's codebase.

Syntax

npx @sylphx/flow codebase [subcommand] [options]

Subcommands

codebase search - Search Codebase
npx @sylphx/flow codebase search <query> [options]

Arguments:

  • query - Search query describing what to find (required)

Options:

  • --limit <number> - Maximum results to return (default: 10)
  • --include-content - Include full code content in results
  • --output <format> - Output format: markdown, json (default: markdown)

Examples:

# Basic search
npx @sylphx/flow codebase search "authentication logic"

# Search with more results
npx @sylphx/flow codebase search "api endpoints" --limit 20

# Include content
npx @sylphx/flow codebase search "database queries" --include-content

# JSON output
npx @sylphx/flow codebase search "error handling" --output json
codebase reindex - Reindex Codebase
npx @sylphx/flow codebase reindex

Rebuilds the codebase search index. Run after significant code changes.

codebase status - Check Index Status
npx @sylphx/flow codebase status

Shows:

  • Index status
  • Number of files indexed
  • Languages detected
  • Database size
  • Last indexed time

flow run - Execute AI Agents

Run AI agents with specific prompts and tasks.

Syntax

npx @sylphx/flow run [prompt] [options]

Arguments

  • prompt - The task or prompt for the agent (optional, will prompt if not provided)

Options

  • --agent <name> - Agent to use: coder, reviewer, writer, orchestrator (default: coder)
  • --target <type> - Force specific target (opencode, claude-code)

Examples

# Use default agent (coder)
npx @sylphx/flow run "implement user authentication"

# Specify agent
npx @sylphx/flow run "review this code for security" --agent reviewer
npx @sylphx/flow run "document the API" --agent writer
npx @sylphx/flow run "implement OAuth with tests" --agent orchestrator

# Interactive mode (prompts for input)
npx @sylphx/flow run --agent coder

Available Agents

  • coder - Code implementation and execution (default)
  • orchestrator - Task coordination and delegation
  • reviewer - Code review and quality assurance
  • writer - Documentation and technical writing

flow mcp - Manage MCP Server

Manage MCP (Model Context Protocol) server and configuration.

Syntax

npx @sylphx/flow mcp [subcommand] [options]

Subcommands

mcp start - Start MCP Server
npx @sylphx/flow mcp start [options]

Options:

  • --disable-knowledge - Disable knowledge base tools
  • --disable-codebase - Disable codebase search tools
  • --disable-time - Disable time utility tools
  • --disable-memory - Disable memory tools (deprecated)
  • --target <type> - Force specific target configuration

Examples:

# Start with all tools (default)
npx @sylphx/flow mcp start

# Start without knowledge tools
npx @sylphx/flow mcp start --disable-knowledge

# Start with only knowledge tools
npx @sylphx/flow mcp start --disable-codebase --disable-time

# Force OpenCode configuration
npx @sylphx/flow mcp start --target opencode

Available MCP Tools:

  • knowledge_search, knowledge_get, knowledge_list - Knowledge base access
  • codebase_search, codebase_reindex, codebase_status - Codebase search
  • time_get_current, time_format, time_calculate - Time utilities
mcp config - Configure MCP Server
npx @sylphx/flow mcp config [options]

Configure MCP server settings and API keys.

mcp list - List MCP Servers
npx @sylphx/flow mcp list

List all configured MCP servers.

mcp add - Add MCP Servers
npx @sylphx/flow mcp add <servers...>

Add additional MCP servers to configuration.

mcp remove - Remove MCP Servers
npx @sylphx/flow mcp remove <servers...>

Remove MCP servers from configuration.

flow hook - Dynamic Hook Content

Load dynamic content for Claude Code hooks (rules, output styles, system info).

Syntax

npx @sylphx/flow hook --type <type> [options]

Options

  • --type <type> - Hook type: session, message (required)
  • --target <target> - Target platform (default: claude-code)
  • --verbose - Show verbose output

Hook Types

  • session - Loads rules + output styles + system info (platform, dirs, hardware, project)
  • message - Loads current system status (time, CPU, memory)

Examples

# Session start hook - all content
npx @sylphx/flow hook --type session --target claude-code

# Message hook - system status
npx @sylphx/flow hook --type message --target claude-code

# Verbose mode - show loading progress
npx @sylphx/flow hook --type session --verbose

What Gets Loaded

Session Hook:

  • Project rules from assets/rules/core.md
  • Output styles from assets/output-styles/*.md
  • System information (platform, directories, CPU, memory)
  • Project information (type, package manager, name, version)

Message Hook:

  • Current time
  • CPU usage
  • Memory usage

🔧 Global Options

These options work with all commands:

  • --help, -h - Show help for command
  • --version, -v - Show version number

📝 Output Formats

Success Messages

✅ Operation completed successfully
✅ Knowledge search completed: 5 results
✅ Codebase indexed: 347 files
✅ MCP server started

Error Messages

❌ Error: Invalid option
❌ Database not found, run: flow init
❌ OpenAI API key not configured

Warning Messages

⚠️ WARNING: Codebase not indexed yet
⚠️ Knowledge base is empty

Info Messages

ℹ️ Database: .sylphx-flow/codebase.db
ℹ️ Found 347 files
ℹ️ MCP server running on stdio

🎯 Common Workflows

1. Initial Setup

# Initialize project
npx @sylphx/flow init

# Check knowledge base
npx @sylphx/flow knowledge status

# Check codebase index
npx @sylphx/flow codebase status

# Start MCP server
npx @sylphx/flow mcp start

2. Working with Knowledge Base

# Search for patterns
npx @sylphx/flow knowledge search "react hooks"

# Get specific guide
npx @sylphx/flow knowledge get "/stacks/react-app"

# List all resources
npx @sylphx/flow knowledge list

3. Searching Codebase

# Semantic search
npx @sylphx/flow codebase search "authentication logic"

# Search with more results
npx @sylphx/flow codebase search "api endpoints" --limit 20

# Reindex after changes
npx @sylphx/flow codebase reindex

4. Using AI Agents

# Implement feature
npx @sylphx/flow run "add user authentication" --agent coder

# Review code
npx @sylphx/flow run "review for security" --agent reviewer

# Write documentation
npx @sylphx/flow run "document the API" --agent writer

# Complex task
npx @sylphx/flow run "implement OAuth with tests" --agent orchestrator

5. Managing MCP Server

# Start with all tools
npx @sylphx/flow mcp start

# Start with specific tools
npx @sylphx/flow mcp start --disable-codebase

# List configured servers
npx @sylphx/flow mcp list

⚙️ Environment Variables

Required for Embeddings

# OpenAI API key for vector embeddings
export OPENAI_API_KEY="your-api-key"

# Optional: Custom embedding model
export EMBEDDING_MODEL="text-embedding-3-small"

# Optional: Custom OpenAI endpoint
export OPENAI_BASE_URL="https://api.openai.com/v1"

Development

# Enable debug mode
export NODE_ENV="development"

# Verbose logging
export DEBUG="sylphx:*"

🐛 Troubleshooting

Knowledge Base Issues

# Check status
flow knowledge status

# Verify database exists
ls -la .sylphx-flow/knowledge.db

# Rebuild index
rm .sylphx-flow/knowledge.db
flow mcp start

Codebase Search Issues

# Check status
flow codebase status

# Reindex
flow codebase reindex

# Verify API key
echo $OPENAI_API_KEY

MCP Server Issues

# Check configuration
cat .claude/mcp.json  # or opencode.jsonc

# Test with verbose output
flow mcp start --verbose

# Verify tools are available
flow knowledge status
flow codebase status

Agent Issues

# Check agents are installed
ls .claude/agents/  # or .kilocode/agents/

# Reinstall agents
flow init --skip-hooks --skip-mcp

🎯 Pro Tips

Efficient Knowledge Search

# Be specific
flow knowledge search "react custom hooks patterns"

# Use categories
flow knowledge list --category stacks

# Get full content when needed
flow knowledge search "security" --include-content

Effective Codebase Search

# Describe what you're looking for
flow codebase search "code that handles user authentication"

# Search for related concepts
flow codebase search "error handling in API routes"

# Reindex regularly
git pull && flow codebase reindex

Agent Best Practices

# Use orchestrator for complex tasks
flow run "implement feature with tests" --agent orchestrator

# Be specific in prompts
flow run "add JWT authentication with refresh tokens" --agent coder

# Use reviewer for quality checks
flow run "review for OWASP vulnerabilities" --agent reviewer

📚 Next Steps

Last Updated: 2025-10-30 | Edit this page | Report Issues

Clone this wiki locally