Gentrace CLI (gentrace)

Command-line bridge between git-ai and the Gentrace API: after each commit it can send commit_attribution telemetry (AI vs human line stats, diff context, and optional prompts) to POST /v1/telemetry.

Package name on npm: @qodly/gentrace · binary: gentrace

Prerequisites

| Requirement | Purpose | |-------------|---------| | Git | Repository detection, hooks, diff, commit metadata. | | git-ai | Records attribution for commits; the CLI reads git-ai output to build telemetry. | | Node.js 18+ or Bun | Runs the published CLI (bin/gentrace.js). Global install via npm uses Node; bunx @qodly/gentrace uses Bun. | | Gentrace account | Sign in to your Gentrace dashboard, create an access token with permission to ingest telemetry (see below). |

Optional:

• curl / bash — used by gentrace install-git-ai for the official git-ai installer on macOS/Linux.

Install

From npm (recommended)

npm install -g @qodly/gentrace

Verify:

gentrace --version

One-off run with npx or bunx

npx @qodly/gentrace@latest doctor
# or, if you use Bun without a global npm install:
bunx @qodly/gentrace@latest doctor

From this monorepo (contributors)

From the repository root (requires Bun or Node.js + npm to build):

bun run --filter @qodly/gentrace install:global

Or from apps/cli (build with npm run build if Bun is not installed):

cd apps/cli && npm run build && npm run install:global

That script builds the CLI and links the gentrace command globally. See scripts/install-global.sh for flags (e.g. --no-build).

Getting started

1. Install git-ai

If git-ai is not installed:

gentrace install-git-ai

This runs the installer from usegitai.com. On Windows (native) it runs the official PowerShell installer; on WSL/macOS/Linux it runs curl … \| bash. After installation, reload your shell or add git-ai to PATH if the binary is not found.

Confirm:

gentrace doctor

doctor checks git, git-ai, API configuration, and API reachability.

2. Create an API token in the dashboard

1. Open your Gentrace web app (for example https://gentrace.4d-ps.com) and sign in.
2. Go to Settings (personal access tokens), e.g. https://gentrace.4d-ps.com/settings.
3. Create New access token.
4. Grant at least telemetry:ingest (or *) so gentrace publish can send batches. Tokens used only for ingest often include telemetry:ingest; gentrace doctor also calls GET /v1/auth/permissions, which requires sufficient IAM on the token (see doctor output if something fails).

Copy the token once — it may not be shown again.

3. Configure the API key (and optional API URL)

Interactive (saved to ~/.config/gentrace/config.json):

gentrace doctor

If no key is set, doctor can prompt for it when a TTY is available.

Explicit:

gentrace config set apiKey 'YOUR_TOKEN_HERE'

Default API base URL is https://gentrace.4d-ps.com/api (paths such as /v1/telemetry are appended to this base). Override if needed:

gentrace config set apiUrl 'https://your-host.example.com/api'

Or use environment variables (highest precedence for URL/key):

export GENTRACE_API_KEY='YOUR_TOKEN_HERE'
export GENTRACE_API_URL='https://your-host.example.com/api'

4. Verify the setup

gentrace doctor

You should see checks for git, git identity, git-ai, API key, HTTP health, and token IAMs for telemetry ingest.

5. Install the post-commit hook (per repository)

In each Git repo where you want automatic publishes after every commit:

cd /path/to/your/repo
gentrace hooks install

Optional second argument: path to the repo root:

gentrace hooks install /path/to/your/repo

The hook runs gentrace publish --daemon in the background (nohup) so commits are not blocked. Logs go to .git/gentrace-publish.log.

Ensure gentrace is on PATH when Git runs hooks (same as in your interactive shell), or set GENTRACE_BIN to the full path of the binary in the environment used by GUI Git clients / CI if needed.

6. Manual publish (optional test)

From a repo with git-ai data for HEAD:

gentrace publish

Optional working directory:

gentrace publish /path/to/repo

Command reference

Global notes:

• gentrace --help / -h — short usage summary.
• gentrace --version / -V — CLI version string.
• Verbose logging — place --verbose, --debug, or -v before the subcommand (or on supported commands such as publish / doctor) to log HTTP details to stderr. Same effect: GENTRACE_DEBUG=1 (or true).

gentrace publish

Collects Git AI attribution and git metadata for a commit in a repository (default HEAD), builds a telemetry batch, and POSTs it to {apiUrl}/v1/telemetry.

Usage

gentrace publish [--verbose|--debug|-v] [--daemon|--background] [--commit <ref>] [--force] [cwd]

| Argument / flag | Description | |-----------------|-------------| | cwd | Optional path to the repository root (defaults to current working directory). | | --commit / -c | Git ref to publish (full or short SHA, branch, tag). Default: HEAD. | | --force / -f | Overwrite an existing commit_attribution for the same user, repository, and commit SHA (API ?force=true). | | --daemon / --background | After a delay, run collection in a style suited to hooks: waits GENTRACE_PUBLISH_DELAY_MS ms if set, otherwise 2500 ms, so git-ai can finish writing stats. Then collects and sends. | | Verbose flags | Extra stderr logs (URL, redacted headers, body preview, response). |

Publish a specific commit

gentrace publish --commit abc1234
gentrace publish -c v1.2.0

Behavior highlights

• Skips the run if the repository id (origin URL, or path fallback) matches skipRepositories (see gentrace skip).
• Requires git-ai on PATH; exits with a hint to run gentrace install-git-ai if missing.
• Resolves API key from GENTRACE_API_KEY or config; may prompt once in a TTY.
• 200: prints accepted count when present in JSON body.
• 409: treated as already recorded (“Commit … already recorded”) unless --force was used.
• 401 / 403: auth error; suggests checking the token and telemetry:ingest.

gentrace doctor

Validates local tools and API connectivity.

Usage

gentrace doctor [--verbose|--debug|-v]

Checks (in order)

1. git on PATH.
2. git user.name and user.email — from git config; may prompt and save globally in a TTY.
3. git-ai on PATH.
4. API key — from env or config; may prompt (with a link to Gentrace Settings) and save in a TTY.
5. GET {apiUrl}/health — unauthenticated liveness.
6. GET {apiUrl}/v1/auth/permissions with X-API-Key — confirms token works and IAMs include telemetry:ingest or * for publish.

Exits 0 if all checks pass, 1 otherwise.

gentrace install-git-ai

If git-ai is already installed, prints the version and exits.

Otherwise (on Unix/WSL) asks for confirmation, then runs:

curl -sSL https://usegitai.com/install.sh | bash

On Windows (native), runs the official PowerShell installer from usegitai.com.

gentrace hooks install / gentrace hooks uninstall

Manage a post-commit shell hook under .git/hooks/post-commit.

Usage

gentrace hooks install [cwd]
gentrace hooks uninstall [cwd]

| Subcommand | Description | |------------|-------------| | install | Ensures .git/hooks exists, then appends or creates a block marked # gentrace-cli post-commit hook that runs nohup gentrace publish --daemon (with GENTRACE_BIN defaulting to gentrace). If an older gentrace hook exists, it may be replaced with the async version. May prompt for API key once. | | uninstall | Removes only the gentrace-marked section; deletes the file if nothing else remains (except a bare #!/bin/sh). |

cwd — optional path to the repo root (default: current directory).

gentrace config

Read or write ~/.config/gentrace/config.json.

Usage

gentrace config                       # print full JSON (apiKey masked)
gentrace config get [key]             # get one key or all if omitted in some forms
gentrace config set <key> <value>     # set scalar keys (see below)
gentrace config unset <key>           # reset key to default
gentrace config <key>                 # same as: config get <key>

Keys

| Key | Type | Description | |-----|------|-------------| | apiUrl | string | API base URL (default includes /api path; see source DEFAULTS). | | apiKey | string | Secret token (get shows a masked value). | | includePrompts | boolean | Set with gentrace config set includePrompts true or false — when true, publish may attach prompt payloads derived from the authorship log (heavier / more sensitive). | | skipRepositories | string[] | Prefer managing via gentrace skip; patterns match repository id (origin URL or path), with simple * glob support. |

gentrace skip

Manage the skip list so gentrace publish (and the hook) no-op for matching repositories.

Usage

gentrace skip add <pattern>
gentrace skip remove <pattern>
gentrace skip list

| Subcommand | Description | |------------|-------------| | add | Append a pattern if not already present. | | remove | Remove an exact pattern entry. | | list | Print all patterns (or a message if empty). |

Matching — * matches any repository; otherwise exact match, or glob if the pattern contains *.

Configuration file

• Path: ~/.config/gentrace/config.json (or $XDG_CONFIG_HOME/gentrace/config.json when set).
• Permissions: written with mode 0600.
• Precedence: GENTRACE_API_URL / GENTRACE_API_KEY override saved values when set.

Environment variables

| Variable | Purpose | |----------|---------| | GENTRACE_API_KEY | API token (overrides config file). | | GENTRACE_API_URL | API base URL (overrides config file). | | GENTRACE_DEBUG | Set to 1 or true for verbose stderr logs. | | GENTRACE_PUBLISH_DELAY_MS | Milliseconds to wait before collecting when using --daemon (default 2500 when daemon; 0 when not daemon unless this env is set). | | GENTRACE_BIN | Used by the post-commit hook: full path to gentrace if it is not on the default PATH for non-interactive Git. |

Related documentation

• Monorepo CLI overview: ../../docs/cli.md
• API / webhooks / IAM concepts: repository root README.md and ARCHITECTURE.md