CLI Reference

# Run directly (no install)
npx @codehabits/cli <command>

# Or install globally
npm install -g @codehabits/cli
codehabits <command>

enable

Enable codehabits intelligence for the current repository. This is the primary setup command. It registers your repo, scans your codebase, fetches PR history, runs AI analysis, and writes intelligence files.

codehabits enable [options]

What it does

1. Detects the GitHub repository from git remotes
2. Fetches repository info from GitHub (visibility, default branch)
3. Registers the repo with codehabits cloud (checks plan limits)
4. Scans codebase: tech stack detection, file patterns, code patterns, config rules import, git contributor analysis, repo docs scanning
5. Fetches merged and closed PRs (up to 12 months lookback)
6. Sends data to the cloud analysis pipeline
7. Writes intelligence files to .codehabits/ (conventions.json, anti-patterns.json, knowledge.json, reviewers.json, meta.json), .codehabits/config.json, and the Agent Skill

Output files

sync

Incrementally update intelligence with the latest PR data. Only fetches PRs merged since the last sync, then merges new pipeline output with your existing intelligence. The CLI sends your current merged snapshot to the API so the cloud stores the same result you write under .codehabits/ (including MCP-approved conventions).

codehabits sync [options]

CI mode

When running in CI/CD (e.g., GitHub Actions), use --ci and set the CODEHABITS_TOKEN and GITHUB_TOKEN environment variables:

- name: Sync codehabits intelligence
  run: npx @codehabits/cli@latest sync --ci
  env:
    CODEHABITS_TOKEN: ${{ secrets.CODEHABITS_TOKEN }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

check

Validate a file against your team's conventions and anti-patterns. Runs entirely locally using your .codehabits/ intelligence files: no network required.

codehabits check <file> [options]

Checks performed

Exits with code 1 if any violations have error severity. Useful as a pre-commit hook or CI check.

Checking src/api/client.ts against team conventions...

  ✗ Catching errors without logging or re-throwing
    → Always log the error with context or re-throw

  ! Using default export - team convention prefers named exports
    → Use named exports: export function/const instead of export default

  1 error, 1 warning, 0 info

show

Display intelligence data in the terminal. Useful for reviewing what codehabits has learned about your team.

codehabits show <type> [options]

Types

summary: High-level overview: repo name, maturity level, counts for all intelligence categories, tech stack, last sync time.

conventions: All conventions grouped by category, with confidence scores, evidence counts, and source attribution.

anti-patterns: Detected anti-patterns sorted by severity, with explanations and correct alternatives.

knowledge: Domain knowledge graph organized by topic (authentication, database, deployment, etc.) with confidence scores.

reviewers: Reviewer expertise map showing who reviews which areas, total reviews, and approval rates.

codehabits show conventions --json | jq '.[] | select(.confidence > 0.9)'

login

Authenticate with codehabits using GitHub OAuth. Opens your browser for authorization, then stores credentials locally.

codehabits login

The CLI uses a device code flow: it displays a verification code, opens the codehabits auth page in your browser, and polls until authentication completes. Credentials are stored securely in your system config directory.

logout

Clear stored credentials from your machine.

codehabits logout

whoami

Display the currently authenticated user.

codehabits whoami

codehabits CLI - Current User
  Login: sriram
  Email: sriram@example.com
  ID:    usr_abc123

token

Manage API tokens for CI/CD and programmatic access. Tokens use the codehabits_ prefix and are stored as SHA-256 hashes on the server.

token create

codehabits token create --name <name> [--scope <scope>] [--repo-id <id>]

token list

List all your API tokens with metadata.

codehabits token list

token revoke

Revoke a token by its ID.

codehabits token revoke <id>

mcp-install

Configure the codehabits MCP server for Cursor. This enables real-time AI tool access to your team's intelligence via the Model Context Protocol.

codehabits mcp-install [options]

MCP tools provided

team assign

Assign an already-enabled repository to a team workspace from the CLI (alternative to the dashboard). Detects the repo from git remote and calls the codehabits API.

codehabits team assign [options]

setup-action

Generate a GitHub Actions workflow that automatically syncs intelligence when PRs are merged.

codehabits setup-action [options]

Generated workflow

Creates .github/workflows/codehabits-sync.yml that:

1. Triggers when a PR is closed (merged) on your default branch
2. Checks out the repository
3. Runs npx @codehabits/cli@latest sync --ci with your tokens
4. Commits updated .codehabits/ and .cursor/skills/ files

Setup steps

1. Create a token: codehabits token create --name "CI"
2. Add it as a repository secret named CODEHABITS_TOKEN in GitHub Settings → Secrets
3. Run codehabits setup-action and commit the workflow file

Environment variables