Commands on gh-velocity

config

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity config#

Inspect, validate, and generate configuration

Synopsis#

Configuration commands for .gh-velocity.yml.

Getting started:

gh velocity config preflight -R owner/repo # analyze repo, suggest config
gh velocity config create # generate starter config
gh velocity config validate # check for errors

Options#

 -h, --help help for config

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

config create

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity config create#

Create a default .gh-velocity.yml in the current directory

Synopsis#

Generate a starter .gh-velocity.yml with sensible defaults.

For a smarter config tailored to your repo, use 'config preflight' first: gh velocity config preflight -R owner/repo

gh-velocity config create [flags]

Examples#

 gh velocity config create

Options#

 -h, --help help for create

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

config discover

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity config discover#

Discover Projects v2 boards and fields linked to a repo

Synopsis#

Queries the GitHub API to find Projects v2 boards linked to the target repository, then lists their fields and status options.

Use this to find the project URL and status field name needed for .gh-velocity.yml configuration.

gh-velocity config discover [flags]

Examples#

 # Discover projects for a remote repo
 gh velocity config discover -R cli/cli

 # JSON output for scripting
 gh velocity config discover -R owner/repo -r json

Options#

 -h, --help help for discover

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

config preflight

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity config preflight#

Analyze a repo and recommend a .gh-velocity.yml configuration

Synopsis#

Preflight queries your repository to build a smart starting configuration.

It inspects:

Labels (to detect bug, feature, and status labels)
A specific Projects v2 board (to find status fields and lifecycle mapping)
Recent merged PRs (to gauge activity and linking patterns)
Recent closed issues (to check label usage)

Use --project-url to include a project board in the analysis. Copy the URL from your browser when viewing the project board.

config show

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity config show#

Display resolved configuration with defaults applied

Synopsis#

Display the fully resolved configuration with all defaults applied.

This shows the effective config that commands will use — including default values for any keys you have not set in your .gh-velocity.yml. Use this to verify that your config is interpreted the way you expect.

The JSON output (-r json) is useful for debugging or piping into other tools.

gh-velocity config show [flags]

Examples#

 gh velocity config show
 gh velocity config show -r json

Options#

 -h, --help help for show

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

config validate

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity config validate#

Validate configuration and report errors

Synopsis#

Validate a .gh-velocity.yml file and report any errors.

Checks include: YAML syntax, known top-level keys, matcher syntax (label:, type:, title:, field: patterns), project URL format, numeric ranges (e.g., hotfix_window_hours), and category name requirements.

Use --velocity to additionally verify that velocity-specific config (effort strategy, iteration strategy, project field names) is correctly configured against your actual GitHub project board.

This command does not make API calls (except with --velocity, which queries the project board to validate field names).

flow

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity flow#

Flow metrics (lead-time, cycle-time, velocity)

Synopsis#

How fast is work flowing through your team?

Flow metrics measure the speed and volume of work:

lead-time Total time from issue creation to closure cycle-time Active work time (start signal to close/merge) throughput Items completed per time window velocity Effort delivered per iteration

Options#

 -h, --help help for flow

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

flow cycle-time

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity flow cycle-time#

Cycle time for an issue, PR, or bulk query

Synopsis#

Cycle time measures how long an issue or PR was actively worked on.

The measurement strategy is set in .gh-velocity.yml:

cycle_time: strategy: issue # work started → issue closed (default) strategy: pr # PR created → PR merged

The issue strategy detects "work started" from lifecycle labels (e.g., label:in-progress). Configure lifecycle.in-progress.match for cycle time metrics.

Single mode: gh velocity cycle-time 42 gh velocity cycle-time --pr 99 Bulk mode: gh velocity cycle-time --since 30d [--until 2026-03-01]

flow lead-time

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity flow lead-time#

Lead time for an issue or bulk query (created → closed)

Synopsis#

Lead time measures the elapsed time from issue creation to close.

Single mode: gh velocity lead-time 42 Bulk mode: gh velocity lead-time --since 30d [--until 2026-03-01]

In bulk mode, returns per-item rows plus aggregate statistics for all issues closed in the given date window.

gh-velocity flow lead-time [<issue>] [flags]

Examples#

 # Single issue
 gh velocity flow lead-time 42
 gh velocity flow lead-time 42 -R cli/cli

 # All issues closed in the last 30 days
 gh velocity flow lead-time --since 30d

 # Custom window, JSON output
 gh velocity flow lead-time --since 2026-01-01 --until 2026-02-01 -r json

Options#

 -h, --help help for lead-time
 --since string Start of date window (YYYY-MM-DD, RFC3339, or Nd relative)
 --until string End of date window (default: now)

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

flow throughput

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity flow throughput#

Count issues closed and PRs merged in a window

Synopsis#

Throughput counts the number of issues closed and pull requests merged in a date window. This is the simplest measure of team output.

Default window is the last 30 days.

gh-velocity flow throughput [flags]

Examples#

 # Last 30 days
 gh velocity flow throughput

 # Last 7 days, JSON output
 gh velocity flow throughput --since 7d -r json

 # Remote repo
 gh velocity flow throughput --since 30d -R cli/cli

Options#

 -h, --help help for throughput
 --since string Start of date window (default: 30d)
 --until string End of date window (default: now)

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

flow velocity

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity flow velocity#

Measure effort completed per iteration (sprint velocity)

Synopsis#

Velocity measures effort completed per iteration and completion rate.

Three effort strategies: count — every item = 1 (default) attribute — map labels/types to effort values via matchers numeric — read effort from a project board Number field

Two iteration strategies: project-field — read boundaries from a ProjectV2 Iteration field fixed — calendar math from length + anchor date

gh velocity

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity#

GitHub velocity and quality metrics

Synopsis#

Compute velocity and quality metrics from GitHub data and post them where the work happens.

Options#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 -h, --help help for gh-velocity
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

issue

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity issue#

Composite detail view for a single issue

Synopsis#

Show everything about a single issue: facts (timestamps, category), metrics (lead time, cycle time), and linked PRs with their cycle times.

This is the recommended command for per-item GitHub Actions automation. Use --post to add a rich comment to the issue when it closes.

gh-velocity issue <number> [flags]

Examples#

 # View issue detail
 gh velocity issue 42

 # Post as a comment on the issue
 gh velocity issue 42 --post

 # JSON output
 gh velocity issue 42 -r json

Options#

 -h, --help help for issue

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

pr

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity pr#

Composite detail view for a single pull request

Synopsis#

Show everything about a single PR: facts (author, timestamps), metrics (cycle time, time to first review, review rounds), and closed issues.

This is the recommended command for per-PR GitHub Actions automation. Use --post to add a rich comment to the PR when it merges.

gh-velocity pr <number> [flags]

Examples#

 # View PR detail
 gh velocity pr 125

 # Post as a comment on the PR
 gh velocity pr 125 --post

 # JSON output
 gh velocity pr 125 -r json

Options#

 -h, --help help for pr

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

quality

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity quality#

Quality metrics for releases

Synopsis#

Is this release good?

Quality metrics analyze your releases:

release Composition, bug ratio, timing, and per-issue breakdown for a specific release tag

Options#

 -h, --help help for quality

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

quality release

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity quality release#

Release velocity and quality metrics

Synopsis#

Compute per-issue lead time, cycle time, release lag, and quality metrics for a release.

Use --discover to show the discovery diagnostic view: which issues and PRs each linking strategy discovered for the release.

gh-velocity quality release <tag> [flags]

Examples#

 # Release metrics with auto-detected previous tag
 gh velocity quality release v2.65.0

 # Explicit previous tag
 gh velocity quality release v2.65.0 --since v2.64.0

 # Discover diagnostic: what did each strategy find?
 gh velocity quality release v2.65.0 --discover

 # Remote repo, JSON output
 gh velocity quality release v2.65.0 -R cli/cli -r json

Options#

 --discover Show discovery diagnostic: what issues/PRs each strategy discovered
 -h, --help help for release
 --since string Override previous tag for commit range (tag name)

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

report

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity report#

Composite dashboard of velocity and quality metrics

Synopsis#

Show a trailing-window report composing lead time, cycle time, throughput, work in progress, and quality metrics.

Default window is the last 30 days. Use --since and --until to customize.

Each section computes independently; a failure in one section does not block others. Sections that require specific config (WIP needs project.id or active_labels; quality needs releases) are gracefully omitted when unavailable.

status

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity status#

Current work status (wip, my-week, reviews)

Synopsis#

What is happening right now?

Status commands show the current state of work:

wip Work in progress — open items with lifecycle labels my-week Personal weekly summary for 1:1 prep reviews Pending and stale pull request reviews

Options#

 -h, --help help for status

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

status my-week

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity status my-week#

Your activity summary for 1:1 prep

Synopsis#

Shows what you shipped, what's blocked, and what's ahead — designed for 1:1 prep.

Sections (in order): Insights Shipping velocity, AI-assisted %, lead time median & p90 Waiting on PRs waiting for first review, stale issues What I shipped Issues closed, PRs merged, PRs reviewed, releases What's ahead Open issues and PRs with status annotations Review queue PRs from others waiting on your review

status reviews

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity status reviews#

Show PRs awaiting review

Synopsis#

Show open pull requests that are waiting for code review.

PRs waiting more than 48 hours are flagged as STALE.

This command shows the work (PRs), not individual reviewers.

gh-velocity status reviews [flags]

Examples#

 # Show review queue
 gh velocity status reviews

 # Markdown for posting to a discussion
 gh velocity status reviews -r markdown

 # JSON for automation
 gh velocity status reviews -r json

Options#

 -h, --help help for reviews

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

status wip

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity status wip#

Show work in progress

Synopsis#

Show items currently in progress.

Uses lifecycle.in-progress.match and lifecycle.in-review.match labels from config to find open issues that are actively being worked on.

Use -R owner/repo to target a specific repo.

gh-velocity status wip [flags]

Examples#

 # Show WIP from configured lifecycle labels
 gh velocity status wip

 # JSON output for CI/automation
 gh velocity status wip -r json

Options#

 -h, --help help for wip

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

version

Mon, 01 Jan 0001 00:00:00 +0000

gh-velocity version#

Print version information

gh-velocity version [flags]

Options#

 -h, --help help for version

Options inherited from parent commands#

 --config string Path to config file (default: .gh-velocity.yml)
 --debug Print diagnostic info to stderr
 --new-post Force a new post (skip idempotent update; implies --post)
 --no-cache Disable disk cache (in-memory deduplication still active)
 --post Post output to GitHub (dry-run by default; set GH_VELOCITY_POST_LIVE=true for live)
 -R, --repo string Repository in owner/name format
 -r, --results strings Output format(s): json, pretty, markdown, html (comma-separated) (default [pretty])
 --scope string Additional GitHub search qualifier(s) ANDed with config scope
 --title string Override discussion title (with --post)
 --write-to string Write result files to this directory (silences stdout)

Commands on gh-velocity

config

gh-velocity config#

Synopsis#

Options#

Options inherited from parent commands#

SEE ALSO#

config create

gh-velocity config create#

Synopsis#

Examples#

Options#

Options inherited from parent commands#

SEE ALSO#

config discover

gh-velocity config discover#

Synopsis#

Examples#

Options#

Options inherited from parent commands#

SEE ALSO#

config preflight

gh-velocity config preflight#

Synopsis#

config show

gh-velocity config show#

Synopsis#

Examples#

Options#

Options inherited from parent commands#

SEE ALSO#

config validate

gh-velocity config validate#

Synopsis#

flow

gh-velocity flow#

Synopsis#

Options#

Options inherited from parent commands#

SEE ALSO#

flow cycle-time

gh-velocity flow cycle-time#

Synopsis#

flow lead-time

gh-velocity flow lead-time#

Synopsis#

Examples#

Options#

Options inherited from parent commands#

SEE ALSO#

flow throughput

gh-velocity flow throughput#

Synopsis#

Examples#

Options#

Options inherited from parent commands#

SEE ALSO#

flow velocity

gh-velocity flow velocity#

Synopsis#

gh velocity

gh-velocity#

Synopsis#

Options#

SEE ALSO#

issue

gh-velocity issue#

Synopsis#

Examples#

Options#

Options inherited from parent commands#

SEE ALSO#

pr

gh-velocity pr#

Synopsis#

Examples#

Options#

Options inherited from parent commands#

SEE ALSO#

quality