CLI & Git Hooks — GitCaptain

Run GitCaptain pre-push analyzers directly inside your terminal and local git hooks.

Upcoming Tool • In Development

The @gitcaptain/cli package is currently in private preview and being finalized for npm and Homebrew. In the meantime, you can analyze any repository immediately using the web dashboard.

Open Dashboard

Package Installation (Preview)

Install the GitCaptain CLI

Install globally via your preferred package manager once released to public registries.

terminal — install

npm install -g @gitcaptain/cli

Interactive Terminal Execution

Fast, deterministic syntax tree traversal executing directly against your local git diff.

zsh — 80x24

$gitcaptain scan --fail-on-risk

[gitcaptain] Ingesting local git diff (3 changed files)...

[gitcaptain] Parsing Tree-sitter AST: TypeScript (2), Python (1)...

[gitcaptain] Traversing cyclomatic decision branches and export symbols...

WARNING: src/auth/session.ts:L48

Potential unbounded token lifetime: maxAge is unset in session cookie configuration.

Recommendation: Specify explicit ttl: 60 * 60 * 24 (24 hours).

Scan Completed: 1 recommendation, 0 critical errorsAST evaluation took 118ms

Workflow Automation

Prevent Broken Pushes with Pre-Push Hooks

By running GitCaptain in your pre-push hook, developers catch downstream regressions and circular imports on their local machine before opening a pull request.

.husky/pre-push

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# Run GitCaptain pre-push AST inspection
# Blocks push if critical cyclomatic complexity or circular imports exist
gitcaptain scan --diff-only --fail-on-risk

Project Configuration

Repository Rule Tuning with .gitcaptain.json

Define custom cyclomatic complexity limits, enable strict circular dependency rejection, and configure parser ignore globs directly in your root directory.

.gitcaptain.json

{
  "$schema": "https://gitcaptain.com/schema.json",
  "version": "1.0",
  "parsers": ["typescript", "javascript", "python"],
  "rules": {
    "maxCyclomaticComplexity": 15,
    "blockCircularImports": true,
    "detectStaleSessions": true
  },
  "ignore": [
    "**/node_modules/**",
    "**/dist/**",
    "**/*.test.ts"
  ]
}

Command Flags & Options

Configure parser scopes, output formats, and threshold levels.

Flag	Type	Default	Description
--diff-only	boolean	true	Inspect only the uncommitted files or staged git diff rather than parsing the entire repository tree.
--fail-on-risk	boolean	false	Exit with non-zero code (exit 1) if high-risk circular dependencies or severe logic bugs are detected.
--complexity-threshold	number	15	Maximum allowable cyclomatic complexity score per function before raising an architectural warning.
--format	string	pretty	Output format: pretty (interactive colored terminal report), json (machine-readable AST payload), or quiet.
--config	string	.gitcaptain.json	Path to custom repository configuration file to override default language parsers and ignore rules.
--quiet	boolean	false	Suppress informational logging and output only warnings and critical errors.

Want Early Access to the Terminal CLI?

We are actively collaborating with teams testing our pre-release binaries. Reach out to join the private developer testing cohort.