EffectPatterns CLI

Search, browse, and install Effect.ts patterns from your terminal using ep.

Installation

Install the CLI globally:

# Install globally with bun (recommended)

bun add -g @effect-patterns/ep-cli

# Or with npm

npm install -g @effect-patterns/ep-cli

Verify: ep --version

Quick start

# List available patterns

ep list

# Search by keyword

ep search "retry"

# Show one pattern in detail

ep show retry-with-backoff

# See supported install targets

ep install list

Command surface

Public commands currently supported:

ep search

ep list

ep show

ep install add

ep install list

ep skills list

ep skills preview

ep skills validate

ep skills stats

ep login

Usage

Authenticateep login

ep login

Pattern discoveryep search / list / show

ep search "error handling"

ep list --difficulty beginner --category error-handling

ep show retry-with-backoff

Install rules into AI toolsep install

Each tool gets its native format. Rules are split into category files (up to 16) so your editor only loads relevant patterns.

# Cursor — .mdc files with YAML frontmatter

ep install add --tool cursor

→ .cursor/rules/effect-*.mdc

# Windsurf — same .mdc format

ep install add --tool windsurf

→ .windsurf/rules/effect-*.mdc

# VS Code / Copilot — single aggregated markdown

ep install add --tool vscode

→ .github/copilot-instructions.md

# Claude Code — .md skill files

ep install add --tool claude

→ .claude/skills/effect-*.md

# Agent — managed section in AGENTS.md

ep install add --tool agent

# Filter by skill level or use case

ep install add --tool cursor --skill-level intermediate --use-case error-handling

# Interactive selection

ep install add --tool windsurf -i

ep install list

Cursor / Windsurf: Each .mdc file includes YAML frontmatter (description, globs, alwaysApply) so your editor can conditionally activate rules.

VS Code / Copilot: All categories are combined into a single .github/copilot-instructions.md file (the Copilot convention).

Claude Code: Plain .md skill files, one per category.

Skillsep skills

Inspect and validate local skill files from your workspace. Skills are organized into 16 categories that map directly to the files created by ep install add.

# List all skill categories and metadata

ep skills list

# Preview the full content of a category

ep skills preview error-management

ep skills preview concurrency

# Validate structure of all skill files

ep skills validate

# Aggregate stats across all skills

ep skills stats

ep skills stats --json

16 categories: Building APIs, Concurrency, Core Concepts, Data Pipelines, Domain Modeling, Error Management, Getting Started, HTTP Requests, Observability, Platform, Resource Management, Schema, Scheduling, Streams, Testing, Tooling & Debugging.

Each category becomes a separate file when you run ep install add for any of the supported tools above (Cursor, Windsurf, VS Code, Claude, Agent). See Install rules into AI tools for the output format per tool.

Rules within each category are tagged by skill level (beginner, intermediate, advanced) and use case, so you can filter with --skill-level and --use-case during install.

Configuration

Pattern API key resolution order:

Environment variable: PATTERN_API_KEY
API key file path: EP_API_KEY_FILE
Config JSON via EP_CONFIG_FILE (or default ~/.config/ep-cli/config.json) with {"apiKey":"..."}
One-off secure (no shell history): printf '%s' "$PATTERN_API_KEY" | ep --api-key-stdin search "retry"

Generate an API key from your account settings.

# Useful env vars

EP_AUTH_URL=https://effecttalk.dev/cli/auth

EFFECT_PATTERNS_API_URL=https://effect-patterns-mcp-server-buddybuilder.vercel.app

EP_SKILLS_DIR=/path/to/skills

JSON output and troubleshooting

ep search "layer" --json

ep install list --json

ep skills stats --json

LOG_LEVEL=debug ep skills stats

401 unauthorized: ensure one API key source is configured.
Skills not found: run from the workspace root or set EP_SKILLS_DIR.
Need machine-readable output: use --json on supported read commands.

Requirements

Bun 1.0+ (recommended) or Node.js with npm
Internet connection (fetches from the Effect Patterns API)