@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
ghp add issue "Title" --priority P1     # Set priority field
ghp add issue "Title" --size M          # Set size field
ghp add issue "Title" --body-file body.md  # Body from file
echo "body" | ghp add issue "Title" --body-stdin  # Body from stdin

# 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 fields                     # Show all project fields and valid values
ghp fields --json              # JSON output for scripts/AI tools

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 | | --keep-branch | With --parallel: never switch branches in the main repo (zero-checkout worktree creation) | | --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) | | --hotfix [ref] | Branch from a tag or commit for hotfix. Omit ref for interactive tag picker | | --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 start 123 --parallel --keep-branch # Create worktree without switching branches in main repo
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)

--keep-branch is designed for non-interactive and multi-agent workflows where other processes are working in the main repo. Instead of switching branches (which --parallel normally does to create the branch), it creates the branch directly from origin/main without any checkout, keeping the main repo's working tree untouched.

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}"

Daily Standup

ghp standup                    # Activity summary (last 24h, your issues)
ghp standup --since 2d         # Activity from last 2 days
ghp standup --timeline         # Flat chronological view (no grouping)
ghp standup --user alice       # Activity for a specific user
ghp standup --json             # JSON output for scripts/AI tools

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