Epic CLI

A command-line tool for managing projects, issues, and pull requests with an integrated workflow featuring git worktrees and optional tmux sessions. Includes static analysis, tracing, and debugger controls.

Installation

# Install dependencies
bun install

# Link globally to use the epic command
bun link

Requirements

• Bun runtime
• GitHub CLI (gh) installed and authenticated
• Git
• Unix-like environment recommended

Note: On Windows, tmux features are not available. Use --no-tmux where offered; all other commands work from PowerShell.

Configuration

Epic CLI uses a configuration file located at .epic/settings.json in your repository. This file is automatically created with default settings when you first use the CLI in a repository.

Default Settings

{
  "baseDirectory": "docs",
  "issuesDirectory": "issues",
  "draftsDirectory": "drafts"
}

Customizing Settings

You can modify .epic/settings.json to change where issues and drafts are stored:

{
  "baseDirectory": "my-custom-folder",
  "issuesDirectory": "tasks",
  "draftsDirectory": "notes"
}

This would make the CLI use my-custom-folder/tasks/ for issues and my-custom-folder/notes/ for drafts.

Usage

Basic Command Structure

epic <command> [options]

Getting Help

# Show general help
epic --help

# Show help for a specific command
epic project --help
epic issue --help
epic pr --help
epic debug --help
epic analyze --help
epic trace --help
epic debugger --help

Commands

Project Commands

Create and manage GitHub repositories.

# Create a new project
epic project new <project-name>

# Create in an organization
epic project new org-name/repo-name

# Use the web template
epic project new my-web-app --web

This command will:

• Create a GitHub repository (private by default)
• Set up a local directory structure
• Initialize with a README.md and initial commit

Issue Commands

Manage GitHub issues with local markdown files.

# Create a new issue (interactive or with title)
epic issue new
epic issue new "Add user authentication"
epic issue new "Refactor database layer" --no-sync

# List issues
epic issue list
epic issue list open
epic issue list closed

# Show issue details
epic issue show CLI-8

# Start working on an issue (creates worktree; optionally tmux)
epic issue start 8
epic issue start CLI-8 --no-tmux
epic issue start 8 --branch          # Branch only, no worktree
epic issue start 8 --no-switch       # Don't switch to tmux session

# Sync changes between local and GitHub
epic issue sync push CLI-8
epic issue sync pull CLI-8

# Download issue from GitHub
epic issue get CLI-8

# Assign issue to user
epic issue assign CLI-8 johndoe

# Close issue and cleanup
epic issue close CLI-8

PR Commands

Work with pull requests.

# Start working on a PR (creates worktree; optionally tmux)
epic pr start 359
epic pr start 359 --no-tmux

Debug Commands

Add or remove debug statements.

# Add debug statements to a function (optionally recursively)
epic debug add myFunction ./src/utils.ts
epic debug add myFunction ./src/utils.ts -r

# Remove debug statements from a function (optionally recursively)
epic debug remove myFunction ./src/utils.ts
epic debug remove myFunction ./src/utils.ts -r

# Remove all debug statements from the project
epic debug remove-all

# Add or remove explicit [DEBUGGER] lines
epic debug add-lines myFunction ./src/utils.ts
epic debug remove-lines myFunction ./src/utils.ts

# Remove all [DEBUGGER] lines
epic debug remove-all-lines

Analyze Commands

Static code analysis and call graph indexing.

# Build call graph index (default: current directory)
epic analyze index ./src

# Show callees for matching functions
epic analyze function closeIssue commands

Trace Commands

Trace execution flows and perform static program slicing.

# Generate execution call stack from runtime [TRACE] logs via stdin
cat logs/dev.log | epic trace stack

# Perform static slicing on a variable using stack JSON via stdin
cat graph.json | epic trace slice handleRequest rawId src/controllers/request.ts

# Chain commands
cat logs/dev.log | epic trace stack | epic trace slice processOrder userId src/services

Debugger Commands

Toggle Epic Debugger mode.

# Enable line-by-line debugging (Variables Snapshot)
epic debugger on

# Disable and revert to standard tracer
epic debugger off

Issue File Format

Issue files are markdown files with a specific format:

# PROJ-123 Feature Title

Issue content and description goes here...

The issue ID (PROJ-123) is automatically added when syncing with GitHub, where PROJ is derived from the repository name.

Workflow

1. Create an issue - epic issue new "Feature title"
2. Sync to GitHub - Automatically synced, or use epic issue sync
3. Start working - epic issue start 123 creates a worktree and tmux session
4. Develop - Work in isolation in the worktree
5. Sync updates - Keep local and GitHub in sync

Development

Project Structure

epic-cli/
├── epic.ts                    # Main entry point (command router)
├── commands/
epic-cli/
├── epic.ts                    # Main entry point (command router)
├── commands/
│   ├── analyze/               # Static analysis
│   │   └── analyze.ts
│   ├── debug/                 # Debug statements
│   │   └── debug.ts
│   ├── debugger/              # Debugger mode toggle
│   │   └── debugger.ts
│   ├── issue/                 # Issue management
│   │   └── issue.ts
│   ├── pr/                    # Pull requests
│   │   └── pr.ts
│   ├── project/               # Project setup
│   │   └── project.ts
│   └── trace/                 # Execution tracing
│       └── trace.ts
├── lib/                       # Shared utilities
├── package.json
└── tsconfig.json

```bash
# Run all tests
bun test

# Run tests for specific command
bun test commands/issue/tests/
bun test commands/project/tests/
bun test commands/debug/
bun test commands/analyze/
bun test commands/trace/

Building

bun run build

Repository

https://github.com/coeus-ventures/epic-cli

License

This project is private and not publicly licensed.