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#
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#
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:
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:
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:
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#
gv get_activity --limit 2 --pretty
{
"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#
gv get_score_details --owner acme-corp --repo backend --pr_number 482 --pretty
{
"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#
gv get_engineer_velocity --username alice --days 30 --pretty
{
"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.
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 writeasks 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_KEYby 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
--prettyto indent it; pipe the compact form straight intojqotherwise. - 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 logoutfirst, then log in again. Make sureGV_URLpoints at the right instance. permission_denied(exit code 4) in CI. TheGV_TOKENyou supplied is missing, revoked, or scoped to the wrong organization. Mint a fresh MCP token and update the secret.transporterrors (exit code 7). The CLI couldn't reach the/mcpendpoint. Check network access and thatGV_URLhas no trailing path after the host.
If anything else looks broken, reach out via the in-app chat or support@headline.com.