CLI Installation & Setup

Platform & Reviews

CLI & Local Tool Configuration & Rules Enterprise & VPC

2 min read

Run GitCaptain AST parsers directly in your local terminal before committing or pushing code.

Run GitCaptain AST parsers directly in your local terminal before committing or pushing code.

Installation Options

npm / npx (Universal)

bash

# Global installation
npm install -g gitcaptain

# Or run instantly without installation
npx gitcaptain review

Homebrew (macOS & Linux)

bash

brew tap gitcaptain/tap
brew install gitcaptain

Standalone Binary (curl)

bash

curl -fsSL https://gitcaptain.com/install.sh | sh

Terminal Authentication

Link your local terminal to your GitCaptain account:

bash

gitcaptain login

This opens your default browser, confirms your GitHub session, and saves a cryptographically signed personal token in ~/.gitcaptain/credentials.

Offline BYOK Mode

You can also run GitCaptain completely decoupled from our cloud service by supplying your provider API key as an environment variable:

bash

export GEMINI_API_KEY="AIzaSyYourSecretKey"
gitcaptain review --local

In this mode, all AST parsing and API calls happen directly from your local terminal.

3 min read

Git Hooks & Husky Integration

Block high-risk bugs, circular imports, and broken typings before code ever leaves a developer machine.

Block high-risk bugs, circular imports, and broken typings before code ever leaves a developer machine.

Husky Pre-Push Setup

Integrate GitCaptain with Husky to guard remote branches against regressions:

bash

# 1. Install husky if not already configured
npm install -D husky
npx husky init

# 2. Add GitCaptain review to the pre-push hook
echo "npx gitcaptain review --fail-on-risk=high" > .husky/pre-push
chmod +x .husky/pre-push

Native .git/hooks Setup

If your repository does not use Husky, configure a native Git hook:

bash

cat << 'EOF' > .git/hooks/pre-push
#!/usr/bin/env bash
echo "🛡️ GitCaptain: Analyzing staged changes before push..."
npx gitcaptain review --diff-only --fail-on-risk=high
if [ $? -ne 0 ]; then
  echo "❌ GitCaptain found high-risk defects. Push aborted."
  exit 1
fi
EOF
chmod +x .git/hooks/pre-push

Pre-Push Enforcement Behavior

1.When you run git push, the hook runs GitCaptain against the outgoing commits.

2.The local AST parser scans syntax deltas in <1 second.

3.If critical security vulnerabilities or syntax errors are detected, the push is canceled before reaching GitHub.

Bypassing Hooks in Emergencies

In situations where a critical hotfix must be pushed immediately:

bash

git push --no-verify

3 min read

CLI Commands & Flags Reference

Complete manual for all GitCaptain terminal flags, output formats, and CI/CD parameters.

Complete manual for all GitCaptain terminal flags, output formats, and CI/CD parameters.

Core Commands

Command	Description
`gitcaptain login`	Authenticate terminal with your GitCaptain account.
`gitcaptain review`	Run AI code review on current branch diff.
`gitcaptain check`	Run quick syntax-tree verification without inference calls.
`gitcaptain config`	Inspect active `.gitcaptain.yml` resolution.
`gitcaptain version`	Print current CLI version and AST engine build.

Review Command Flags

bash

gitcaptain review [flags]

--diff-only: Inspect only uncommitted git changes instead of full branch.

--staged: Inspect only files staged with git add.

--fail-on-risk=: Set exit code to 1 if risk meets threshold (low, medium, high, critical).

--provider=: Override configured provider (google, groq, openrouter).

--json: Output findings as machine-readable JSON for integration into custom scripts.

CI/CD Pipeline Parameters

Run GitCaptain in GitHub Actions or GitLab CI runners:

yaml

# .github/workflows/gitcaptain.yml
name: GitCaptain CLI Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run GitCaptain Review
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          npx gitcaptain review --fail-on-risk=critical --json > findings.json

Previous Track

Platform & Reviews

Next Track

Configuration & Rules