Integrations GitVelocity CLI Menu

GitVelocity CLI

Drive your velocity data from the shell with the gv CLI — same tools and auth as the MCP server

Overview#

The GitVelocity CLI (gv) is a thin command-line client over the MCP Server. Same tools, same auth, same payloads — but driven from the shell, where you can pipe it through jq, loop it, and run it from CI. It hits the same /mcp endpoint and authenticates with the same OAuth flow, so every read-only tool you can call from Claude is also a gv subcommand.

Install#

bash
brew install headlinevc/tap/gitvelocity
gv version

Prebuilt binaries for Windows and air-gapped installs are also published on the dist repo's Releases page.

Quick start#

bash
gv auth login                       # opens browser, OAuth + PKCE loopback
gv auth whoami --pretty             # confirm who you are and which org
gv tools --pretty                   # list every available tool
gv get_dashboard_overview --pretty  # run a tool

Tools are called by name. Pass arguments as one JSON object with --json '{...}', or as per-property flags:

bash
gv get_engineer_velocity --json '{"username":"alice","days":30}'
gv get_engineer_velocity --username alice --days 30

Authentication#

The CLI authenticates against the MCP server with OAuth 2.0 authorization_code + PKCE (S256). Running gv auth login opens your browser and starts a loopback listener on an ephemeral local port; once you sign in and approve, the callback completes and the token is captured. The token is for the workspace you have open in GitVelocity when you approve, so switch workspaces in the app first if you need a different one.

Tokens are stored in your OS keyring — macOS Keychain, Windows Credential Manager, or libsecret on Linux — falling back to a 0600 file when no keyring is available. Dynamic Client Registration (RFC 7591) means no admin has to mint a client_id for you; the CLI registers itself.

Command Purpose
gv auth login Browser OAuth flow; stores tokens in the keyring
gv auth whoami Show the authenticated user and organization
gv auth refresh Refresh the access token without re-authorizing
gv auth logout Remove stored tokens from the keyring

Configuration#

The CLI reads configuration from environment variables. It also loads ~/.env on startup, so you can keep these there instead of exporting them per shell.

Variable Default Purpose
GV_URL https://gitvelocity.dev Base URL of the GitVelocity instance to talk to
GV_TOKEN (none) Pre-minted MCP token for CI / non-interactive use — bypasses the browser flow
GV_CLIENT_ID (none) Pre-registered OAuth client ID (skip DCR); requires GV_OAUTH_PORT
GV_OAUTH_PORT (ephemeral) Pin the loopback callback port instead of using a random one

Non-interactive / CI#

For CI and other non-interactive contexts, set GV_TOKEN to a pre-minted MCP token and run any tool directly. No gv auth login, no browser, no keyring:

bash
GV_TOKEN=<mcp-token> gv get_dashboard_overview --pretty

Available tools#

The CLI exposes the same read-only tool set as the MCP server. See the MCP Server doc for the full tool table and what each one returns. For live schemas, use:

bash
gv tools              # list all tools
gv <tool> --help      # show one tool's parameters

Examples#

Every response is JSON. The samples below are truncated (…) — run with --pretty to see the full payload.

Scored activity feed#

bash
gv get_activity --limit 2 --pretty
jsonc
{
  "items": [
    {
      "score_id": 187668,
      "repo": "acme-corp/backend",
      "pr_number": 482,
      "score": 14,
      "title": "Gate optimistic association UI on server success",
      "html_url": "https://github.com/acme-corp/backend/pull/482",
      "state": "closed",
      "merged": true,
      "author_login": "alice",
      "username": "alice",
      "source_type": "pr",
      "model": "claude-sonnet-4-6",
      "created_at": "2026-06-23T17:04:00.000Z",
    },
    // … one more item
  ],
  "total": 2437,
  "page": 1,
  "limit": 2,
  "totalPages": 1219,
  "metadata": {
    "repositories": [{ "repo": "acme-corp/backend", "count": 807 }],
    "authors": [{ "login": "alice", "displayName": "Alice", "count": 719 }],
    "scoreRange": { "min": 1, "max": 89 },
    // … activityRange
  },
}

Full score breakdown#

bash
gv get_score_details --owner acme-corp --repo backend --pr_number 482 --pretty
json
{
  "repo": "acme-corp/backend",
  "prNumber": 482,
  "sourceType": "pr",
  "totalScore": 14,
  "totalFactors": "36 × 0.4 (Small ESF) = 14.4 → 14",
  "rubric": {
    "scope": {
      "score": 8,
      "maxScore": 20,
      "factors": "Six files under src/checkout/, all in the payment-confirmation path. No new endpoint and no migration."
    },
    "architecture": {
      "score": 5,
      "maxScore": 20,
      "factors": "The success check moves out of confirmOrder() into a shared isSettled() predicate, called from three sites. No new module boundary, no new dependency."
    },
    "implementation": {
      "score": 7,
      "maxScore": 20,
      "factors": "awaitSettlement() now awaits the gateway response before resolving, so a rejected charge no longer resolves as success. Null and error branches return early rather than falling through."
    },
    "risk": {
      "score": 6,
      "maxScore": 20,
      "factors": "Changes what the confirmation screen shows after a declined card, which is visible to every checkout. No schema change, no auth change, no migration."
    },
    "quality": {
      "score": 9,
      "maxScore": 15,
      "factors": "isSettled.test.ts covers the settled, declined and timeout cases. No test drives the real CheckoutForm."
    },
    "perfSecurity": {
      "score": 1,
      "maxScore": 5,
      "factors": "Input validation on the gateway response shape. No benchmark accompanies the change."
    }
  },
  "schemaVersion": "v7",
  "createdAt": "2026-06-23T17:04:32.020Z"
}

One engineer's velocity#

bash
gv get_engineer_velocity --username alice --days 30 --pretty
jsonc
{
  "averageScore": 26,
  "totalPRs": 45,
  "maxScore": 78,
  "minScore": 1,
  "scoreDistribution": { "high": 0, "medium": 10, "low": 40 },
  "monthlyTrends": [{ "month": "2026-06", "score": 26, "prCount": 50 }],
  "recentActivity": [
    {
      "repo": "acme-corp/backend",
      "pr_number": 482,
      "score": 14,
      "title": "Gate optimistic association UI on server success",
      "merged": true,
      "created_at": "2026-06-23T17:04:32.020Z",
      // … more fields per PR
    },
    // … more PRs
  ],
  "username": "alice",
  "repositoriesContributed": ["acme-corp/backend", "acme-corp/web"],
}

Score your own work locally (gv score)#

gv score scores the changes you authored in a repo you've cloned. It runs on your machine with your own model key and uploads only the scores to your personal workspace. It's meant for repos you can read but can't connect to GitVelocity.

bash
gv auth login --scope write   # once, with your personal workspace open in GitVelocity
cd ~/code/some-repo
gv score --dry-run --max 3    # score 3 changes and print them; nothing is uploaded
gv score                      # score up to 100 new changes and upload them

Before you start:

  • Use your personal workspace. Uploads are accepted only into a personal workspace you own, with your GitHub login verified. --scope write asks for permission to upload scores, and the token is for the workspace you have open when you approve.
  • Set your model key. The key is read from an environment variable (ANTHROPIC_API_KEY by default) and sent only to your model provider. There is no flag for the key itself.

What leaves your machine. Each diff goes only to the model provider you choose, called directly with your key. GitVelocity receives the scores, the model's notes on each change, and each change's size (effective lines and file count), never the diff or your code. The notes are prose about your change, so they can name files and functions. gv removes any code the model quotes before uploading, and GitVelocity rejects notes that still contain code. --dry-run shows exactly what would be sent.

What gets scored. gv reads the history of --ref (default HEAD) back to --since (default 24m, two years, so your multiplier has a baseline). Pull request merge commits and squash merges ending in (#N) count as pull request N (a merge counts as yours when you wrote the first commit on its branch); other commits you authored count as direct commits, and GitVelocity stores those as commits rather than pull requests. Authors are matched by --author (default: your git config user.email). Each run scores the newest changes not uploaded before, so run it again to go further back.

Before sending anything, gv shows how many changes it will score, the provider, the model and an estimated cost, and asks you to confirm. Pass --yes to skip the prompt. Without --dry-run, it first checks that your token can upload to a personal workspace, so no model spend is wasted on an upload that would be refused.

Flag Default Purpose
--provider anthropic anthropic, openai or openrouter
--model depends on the provider Model ID to score with
--key-env the provider's usual variable Name of the environment variable that holds your key
--since 24m Nd, Nw, Nm (months), Ny, or YYYY-MM-DD
--max 100 Most changes scored per run
--dry-run off Score and print; upload nothing
--yes, -y off Skip the cost confirmation
--author git config user.email Author email to match (repeatable)
--ref HEAD Branch or revision to read
--repo from --remote owner/name the scores are filed under

Run gv score --help for the full list.

In GitVelocity, these scores show a Scored locally badge. A local score never replaces one GitVelocity computed itself. Different models score the same change differently, so to compare with a company workspace, score with the model that workspace uses (--provider and --model).

gv score exits with code 4 when the token lacks upload permission, or the workspace isn't a personal one you own with a verified GitHub login. It exits with 2 for a usage problem such as a missing key.

Output contract#

  • stdout is always JSON. Add --pretty to indent it; pipe the compact form straight into jq otherwise.
  • stderr is human progress. Suppress it with --quiet.
  • Mutating tools support --dry-run (none of today's read-only tools mutate state, but the flag is honored where applicable).

Exit codes:

Code Meaning
0 Success
1 General error
2 Usage error
3 Not found
4 Permission denied
5 Conflict
7 Transport error

Troubleshooting#

  • The browser login keeps looping. Re-run gv auth login. If a stale token is in the way, gv auth logout first, then log in again. Make sure GV_URL points at the right instance.
  • permission_denied (exit code 4) in CI. The GV_TOKEN you supplied is missing, revoked, or scoped to the wrong organization. Mint a fresh MCP token and update the secret.
  • transport errors (exit code 7). The CLI couldn't reach the /mcp endpoint. Check network access and that GV_URL has no trailing path after the host.

If anything else looks broken, reach out via the in-app chat or support@headline.com.