Announcing the EffectPatterns CLI

The EffectPatterns CLI is now live.

If you use Effect in real projects, you should not have to stop what you are doing, open a browser, and hunt for examples every time you need a pattern. The CLI brings the pattern library directly into your terminal so you can search, inspect, and apply patterns where you already work.

What ships today

The CLI package is published as @effect-patterns/ep-cli and exposes a focused command surface:

• search
• list
• show
• install add
• install list
• skills list
• skills preview
• skills validate
• skills stats
• login

This is the stable end-user surface for discovering patterns and installing AI tool rules.

Install in under a minute

# Bun (recommended)
bun add -g @effect-patterns/ep-cli

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

# verify
ep --version

Once installed, ep is available globally in your shell.

Core command workflow

# 1) list patterns
ep list

# 2) search by keyword
ep search "retry"

# 3) inspect one pattern in detail
ep show retry-with-backoff

# 4) see install targets
ep install list

This is the fastest path from "I need an Effect pattern" to "I have a concrete example in front of me."

Getting started

Managing API keys by hand is a chore. ep login automates it.

Run this first:

ep login

What happens:

1. The CLI opens a browser window for authentication.
2. It starts a local callback server.
3. After login, the callback captures your key.
4. The CLI writes config JSON to EP_CONFIG_FILE if set, otherwise $XDG_CONFIG_HOME/ep-cli/config.json (fallback ~/.config/ep-cli/config.json).

If your API is protected, pattern fetching and AI rule installation require authentication. ep login is the direct setup path.

Pattern discovery from the terminal

The discovery flow is intentionally simple:

1. ep search "<query>" to narrow by concept.
2. ep list with filters when you want breadth.
3. ep show <pattern-id> when you want full detail.

Examples:

ep search "error handling"
ep list --difficulty beginner --category error-handling
ep show handle-errors-with-catch

Use this when you are coding and want to stay in-context, not tab-switching between docs pages.

Install rules into AI coding tools

The CLI installs EffectPatterns rule bundles for supported tools. Each tool gets its native format, with rules split into category files so your editor only loads relevant patterns.

# Cursor — .mdc files with YAML frontmatter in .cursor/rules/
ep install add --tool cursor

# Windsurf — same .mdc format in .windsurf/rules/
ep install add --tool windsurf

# VS Code / Copilot — single .github/copilot-instructions.md
ep install add --tool vscode

# Claude Code — .md skill files in .claude/skills/
ep install add --tool claude

# 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

# list available install targets
ep install list

Cursor and Windsurf files include YAML frontmatter (description, globs, alwaysApply) so your editor can conditionally activate rules. VS Code uses a single aggregated markdown following the Copilot instructions convention. Claude gets plain .md skill files, one per category.

Skills commands for local validation and inspection

If you work with local skills, the CLI includes dedicated commands:

ep skills list
ep skills preview error-management
ep skills validate
ep skills stats

This keeps your skill workflows and Effect pattern workflows in one place.

Why this matters in practice

For most teams, Effect adoption slows down at the same point: people know the primitives, but they need concrete production patterns quickly. The CLI reduces that friction:

• You can discover patterns while coding, without leaving the terminal.
• You can inspect exact pattern IDs and examples before applying them.
• You can distribute the same rule sets across editors and agent tools.

It is designed for the moment where you are in a task, blocked on implementation detail, and need an answer now.

Requirements

• Bun 1.0+ (recommended) or Node.js with npm
• Internet access to the Effect Patterns API

Read the full docs

• CLI docs page: /cli
• Pattern browser: /patterns
• API key management: /settings/api-keys

What is next

This release focuses on stable core workflows: discovery, install, and skills support. Next iterations will continue improving command ergonomics and the surrounding toolchain integrations while keeping the command surface explicit and script-friendly.

If you hit edge cases or want new workflows, open an issue on GitHub.