Package Exports

@bretwardjames/ghp-cli
@bretwardjames/ghp-cli/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@bretwardjames/ghp-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@bretwardjames/ghp-cli

GitHub Projects CLI - manage project boards from your terminal.

Part of the GHP monorepo. Works alongside the VS Code/Cursor extension for a complete GitHub Projects workflow.

Installation

npm install -g @bretwardjames/ghp-cli

Breaking Changes in v0.7.0

Short flags removed to fix semantic collisions (same letter meant different things):

Removed	Use Instead	Command
`-f`	`--flat`	`work`
`-a`	`--assign`	`add issue/epic`
`-c`	`--create`	`pr`
`-m`	`--mine`	`plan`
`-t`	`--type`	`progress`
`-s`	`--show`	`config`
`-p`	`--parent`	`set-parent`
`-b`	`--browser`	`open`
`-l`	`-L`	`--labels` in `add`

Migration: Update scripts to use long-form flags:

ghp work -f       →  ghp work --flat
ghp pr -c         →  ghp pr --create
ghp plan -m       →  ghp plan --mine
ghp open 123 -b   →  ghp open 123 --browser

Quick Start

# Authenticate with GitHub
ghp auth

# View your assigned items
ghp work

# View project board
ghp plan

# Start working on an issue
ghp start 123

Commands

Authentication

ghp auth                       # Check authentication status
ghp auth --status              # Display auth status and setup guide

Viewing Work

ghp work                       # Your assigned items
ghp work --all                 # All items (not just yours)
ghp work --status "In Progress" # Filter by status
ghp work --hide-done           # Hide completed items
ghp work --group priority      # Group by field
ghp work --sort -priority      # Sort (prefix - for descending)
ghp work --slice type=Bug      # Filter by field value
ghp work --list                # Simple list format
ghp work --flat                # Flat table format
ghp work --json                # JSON output for scripts/AI tools

ghp plan                       # Project board view
ghp plan --mine                # Only items assigned to you
ghp plan --unassigned          # Only unassigned items
ghp plan --status "Backlog"    # Filter by status (repeatable)
ghp plan --slice type=Bug      # Filter by field value (repeatable)
ghp plan --view "Sprint 1"     # Filter by project view
ghp plan --group status        # Group by field
ghp plan --sort priority       # Sort by field
ghp plan --all                 # Include done items
ghp plan --hide-done           # Exclude completed items
ghp plan --list                # Simple list format
ghp plan --json                # JSON output for scripts/AI tools
ghp plan bugs                  # Use configured shortcut

ghp slice                      # Interactive field filtering
ghp slice -f Priority -v High  # Filter by specific field/value
ghp slice --list-fields        # List all available fields

Issue Management

# Create issues
ghp add "Issue title"                   # Create issue (shorthand)
ghp add issue "Issue title"             # Create issue (explicit)
ghp add issue "Title" --body "desc"     # With description
ghp add issue "Title" -e                # Open editor for body
ghp add issue "Title" --template bug    # Use specific template
ghp add issue "Title" --ai              # AI-expand brief title
ghp add issue "Title" --status "Backlog"     # Set initial status
ghp add issue "Title" --labels "bug,urgent"  # Apply labels
ghp add issue "Title" --assign          # Assign yourself
ghp add issue "Title" --parent 42       # Create as sub-issue

# Create epics
ghp add epic "Epic title"               # Create epic (issue with epic label)
ghp add epic "Auth system" --ai         # AI breakdown into sub-issues
ghp add epic "Title" --ai -x            # Execute AI plan (create issues)
ghp add epic "Title" --ai -c "context"  # Provide additional context

ghp add --list-templates                # List available templates

ghp open 123                   # View issue details in terminal
ghp open 123 --browser         # Open in browser

ghp edit 123                   # Edit issue in $EDITOR

ghp comment 123                # Add comment (opens editor)
ghp comment 123 -m "message"   # Add comment inline

ghp move 123 "In Review"       # Change issue status

ghp set-field 123 Priority High  # Set any project field

ghp assign 123                 # Assign yourself
ghp assign 123 @user1 @user2   # Assign specific users
ghp assign 123 --remove @user  # Remove assignee

ghp label 123 bug urgent       # Add labels
ghp label 123 bug --remove     # Remove label

Parent/Child Relationships (Sub-Issues)

ghp set-parent 123 --parent 42    # Set parent issue
ghp set-parent 123 --remove       # Remove parent
ghp progress 42                   # Show epic progress with sub-issues

Workflow

ghp start 123                  # Start working on issue

The start command:

Creates or links a branch
Updates issue status to "In Progress"
Assigns you if not already assigned
Applies the active label

Options:

Option	Description
`--parallel`	Create worktree instead of switching branches
`--worktree-path <path>`	Custom worktree location
`--branch-action <action>`	`create`, `link`, or `skip`
`--assign <action>`	`reassign`, `add`, or `skip`
`--from-main`	Create branch from main (when not on main)
`--force`	Proceed with uncommitted changes
`--force-defaults`	Non-interactive mode

ghp done 123                   # Mark issue as done

Removes active label and offers to clean up worktree if one exists.

ghp stop 123                   # Stop working on issue (keep in current status)
ghp stop                       # Stop working on current branch's issue

Removes active label without changing status. Useful when switching tasks.

ghp pr                         # Show PR status for current branch
ghp pr 123                     # Show PR for specific issue
ghp pr --create                # Create PR for current branch
ghp pr --open                  # Open PR in browser

Branch Management

ghp switch 123                 # Switch to issue's linked branch
ghp switch 123 --parallel      # Open in worktree instead
ghp switch 123 --worktree-path /custom/path

ghp link-branch 123            # Link current branch to issue
ghp link-branch 123 feature/x  # Link specific branch

ghp unlink-branch 123          # Remove branch link from issue

ghp sync                       # Sync active label with current branch

Parallel Work Mode (Worktrees)

Work on multiple issues simultaneously:

ghp start 123 --parallel       # Create worktree for issue
ghp switch 456 --parallel      # Open existing issue in worktree
ghp worktree list              # List all active worktrees
ghp worktree list --json       # JSON output for scripts/AI tools
ghp worktree remove 123        # Remove worktree for issue
ghp worktree remove 123 --force  # Force remove (uncommitted changes)

Branch Dashboard

View comprehensive branch changes with extensible hook system:

ghp dashboard                  # Full dashboard (commits, files, stats, hooks)
ghp dashboard --diff           # Show full unified diff
ghp dashboard --commits        # Commit history only
ghp dashboard --files          # Changed files only
ghp dashboard --stats          # Diff statistics only
ghp dashboard --json           # JSON output for scripts/tools
ghp dashboard --base main      # Compare against specific base branch

Dashboard Hooks - Integrate external tools (AI context, test results, etc.):

ghp dashboard hooks list                # List registered hooks
ghp dashboard hooks add <name>          # Register a new hook
  --command <cmd>                       # Command to execute
  --category <cat>                      # Category for grouping (optional)
  --display-name <name>                 # Display name (optional)
  --timeout <ms>                        # Timeout in milliseconds (default: 5000)
ghp dashboard hooks remove <name>       # Remove a hook
ghp dashboard hooks enable <name>       # Enable a hook
ghp dashboard hooks disable <name>      # Disable a hook
ghp dashboard hooks show <name>         # Show hook details

Hook commands receive --branch and --repo arguments and return JSON:

{
  "success": true,
  "data": {
    "title": "Section Title",
    "items": [{ "label": "Item", "value": "Description" }]
  }
}

See docs/hooks/README.md for the full hook API.

Event Hooks

Integrate external tools by registering hooks that run on lifecycle events:

ghp hooks list                      # List registered hooks
ghp hooks add <name>                # Register a new hook
  --event <event>                   # Event: issue-created, issue-started, pre-pr, pr-creating,
                                    #        pr-created, pr-merged, worktree-created, worktree-removed
  --command <cmd>                   # Shell command with ${var} templates
  --timeout <ms>                    # Timeout in milliseconds (default: 30000)
  --mode <mode>                     # Execution mode (see below)
  --continue-prompt <text>          # Custom prompt for interactive mode
ghp hooks remove <name>             # Remove a hook
ghp hooks enable <name>             # Enable a hook
ghp hooks disable <name>            # Disable a hook
ghp hooks show <name>               # Show hook details

Hook Modes:

Mode	Behavior
`fire-and-forget`	Silent execution, logged only, never aborts (default)
`blocking`	Shows output on failure, non-zero exit aborts workflow
`interactive`	Always shows output, prompts user to continue/abort/view

Events and Template Variables:

Event	Trigger	Variables
`issue-created`	After `ghp add`	`${issue.number}`, `${issue.title}`, `${issue.body}`, `${issue.url}`, `${issue.json}`, `${repo}`, `${_event_file}`
`issue-started`	After `ghp start`	`${issue.number}`, `${issue.title}`, `${issue.body}`, `${issue.url}`, `${issue.json}`, `${branch}`, `${repo}`, `${_event_file}`
`pre-pr`	Before PR creation	`${branch}`, `${base}`, `${changed_files}`, `${diff_stat.additions}`, `${diff_stat.deletions}`, `${diff_stat.files_changed}`, `${repo}`, `${_event_file}`
`pr-creating`	Just before GitHub API call	`${title}`, `${body}`, `${branch}`, `${base}`, `${repo}`, `${_event_file}`
`pr-created`	After `ghp pr --create`	`${pr.number}`, `${pr.title}`, `${pr.body}`, `${pr.url}`, `${pr.json}`, `${branch}`, `${repo}`, `${_event_file}`
`pr-merged`	After `ghp merge`	`${pr.number}`, `${pr.title}`, `${pr.url}`, `${pr.merged_at}`, `${pr.json}`, `${branch}`, `${base}`, `${repo}`, `${_event_file}`
`worktree-created`	After `ghp start --parallel`	`${worktree.path}`, `${worktree.name}`, `${branch}`, `${issue.number}`, `${issue.title}`, `${issue.url}`, `${issue.json}`, `${repo}`, `${_event_file}`
`worktree-removed`	After `ghp worktree remove`	`${worktree.path}`, `${worktree.name}`, `${branch}`, `${issue.number}`, `${issue.title}`, `${issue.url}`, `${issue.json}`, `${repo}`, `${_event_file}`

Note: ${_event_file} is a path to a temporary JSON file containing the full event payload. Use this for complex data like arrays or when shell escaping becomes problematic.

Hook Failure Behavior:

By default, hooks use fail-fast - if one hook aborts, subsequent hooks don't run. Configure globally or per-event:

// ~/.config/ghp-cli/config.json
{
  "hooks": {
    "onFailure": "continue"  // Run all hooks even if some fail
  }
}

// ~/.config/ghp-cli/event-hooks.json
{
  "hooks": [...],
  "eventDefaults": {
    "pre-pr": { "onFailure": "fail-fast" },     // Critical: stop on failure
    "issue-created": { "onFailure": "continue" } // Non-critical: run all
  }
}

Example: Ragtime Integration

# Register hook to generate context when starting work
ghp hooks add ragtime-context \
  --event issue-started \
  --command "ragtime new-branch \${issue.number} --issue-json '\${issue.json}'"

# Now `ghp start 42` will:
# 1. Create/switch to branch
# 2. Run ragtime to generate context in .claude/memory/

Example: Pre-PR Validation (Blocking)

# Block PR creation if tests fail (runs BEFORE the PR is created)
ghp hooks add run-tests \
  --event pre-pr \
  --mode blocking \
  --command "npm test"

Example: Interactive Code Review

# Prompt for review before PR creation
ghp hooks add ai-review \
  --event pre-pr \
  --mode interactive \
  --continue-prompt "AI review complete. Proceed with PR?" \
  --command "ai-review check --branch \${branch}"

Example: AI-Generated PR Description

# Use pr-creating to suggest PR title/body (hook can modify them)
ghp hooks add ai-description \
  --event pr-creating \
  --command "ai-pr-helper suggest --branch \${branch} --base \${base}"

Example: Tailscale Funnel Integration

# Set up Tailscale funnel when a worktree is created
ghp hooks add ts-funnel-up \
  --event worktree-created \
  --command "ts-magic up \${worktree.path}"

# Tear down funnel when worktree is removed
ghp hooks add ts-funnel-down \
  --event worktree-removed \
  --command "ts-magic down --port \${issue.number}"

Agent Management

Manage Claude agents running in parallel worktrees:

ghp agents list                # List all running agents
ghp agents list --json         # JSON output for scripts/AI tools
ghp agents stop 123            # Stop agent for specific issue
ghp agents stop --all          # Stop all agents
ghp agents watch               # Real-time agent dashboard

AI-Assisted Features

ghp add issue "Fix login" --ai    # Expand brief title into full issue
ghp add epic "Auth system" --ai   # Break down epic into sub-issues
ghp add epic "Title" --ai -x      # Execute plan (create issues)
ghp pr --ai-description           # Generate PR description from changes

Note: ghp plan-epic is deprecated. Use ghp add epic --ai instead.

Configuration

ghp config                     # Open config in editor
ghp config --show              # Display all settings with sources
ghp config -w                  # Edit workspace config (shared with team)
ghp config -u                  # Edit user config (personal)
ghp config sync                # Sync settings with VS Code/Cursor

MCP Server

ghp mcp                        # Show MCP configuration
ghp mcp --config               # Show config JSON
ghp mcp --install              # Auto-configure Claude Desktop

Self-Update

ghp update                     # Update ghp packages to latest version
ghp update --check             # Check for updates without installing
ghp update --yes               # Skip prompts, update all packages
ghp update --beta              # Force update to beta versions
ghp update --stable            # Force update to stable versions

Auto-detects your current release channel (beta/stable) and updates accordingly.

Configuration

Config files:

User: ~/.config/ghp-cli/config.json
Workspace: .ghp/config.json (commit this for team settings)

Settings are merged: defaults → workspace → user (later overrides earlier).

All Options

Option	Default	Description
`mainBranch`	`"main"`	Main branch name
`branchPattern`	`"{user}/{number}-{title}"`	Branch naming. Tokens: `{user}`, `{number}`, `{title}`
`startWorkingStatus`	`"In Progress"`	Status when starting work
`doneStatus`	`"Done"`	Status when marking done
`worktreePath`	`"~/.ghp/worktrees"`	Base directory for worktrees
`worktreeCopyFiles`	`[".env", ".env.local"]`	Files copied to new worktrees
`worktreeSetupCommand`	`"pnpm install"`	Setup command for new worktrees
`worktreeAutoSetup`	`true`	Auto-run setup in new worktrees
`shortcuts`	`{}`	Named filter combinations

Example Config

{
  "mainBranch": "main",
  "branchPattern": "{user}/{number}-{title}",
  "startWorkingStatus": "In Progress",
  "doneStatus": "Done",
  "worktreePath": "~/dev/worktrees",
  "worktreeCopyFiles": [".env", ".env.local", ".env.test"],
  "worktreeSetupCommand": "npm ci",
  "worktreeAutoSetup": true,
  "shortcuts": {
    "bugs": { "status": "Backlog", "slice": ["type=Bug"] },
    "mine": { "mine": true, "status": "In Progress" }
  }
}

Requirements

Node.js >= 18
GitHub CLI (gh) authenticated, or GITHUB_TOKEN environment variable
GitHub account with Projects access

License

MIT