CLI reference.

One binary, every surface of the engine. This page covers the commands you will use daily. The binary ships more — codetitan --help lists all of them, and § 08 below summarizes the rest. Everything here is verified against the published @noalia/codetitan@2.1.8.

npx @noalia/codetitan@latest analyze . --no-ai

No signup, no config, no quota. Local analysis is unmetered.

§ 01 · analyze

Scans a path and emits findings. The command you will run most.

codetitan analyze [path] [flags]

Output:

• --format <type> · console · json · markdown · sarif · sbom (CycloneDX / SPDX). Default: console.
• --output <file> · write the report to a file instead of stdout

Gating (for CI):

• --fail-on <severity> · exit 1 if findings at this severity or above: critical · high · medium · never
• --risk-threshold <number> · exit 1 if the repo-specific PR Risk Score meets or exceeds this value. Default: 80.
• --min-confidence <number> · only show findings at or above this confidence, 0–100

Scope:

• --changed-only · only files changed relative to git HEAD or --diff-base. Fast enough for pre-commit.
• --diff-base <ref> · the base ref for --changed-only (for example origin/main or a PR base SHA)
• --level <1-8> · analysis depth. Default: 4.
• --single-file / --with-context · when the target is one file: analyze it alone (faster) or with full project context

Dependencies:

• --deps · scan direct dependencies for known CVEs via OSV (needs package.json and a network call to api.osv.dev)
• --deps-transitive · the full dependency tree via package-lock.json. Slower.

Cold audits and sharing:

• --public <owner/repo> · shallow-clone a public GitHub repo to a temp directory and analyze it. Defaults to --no-ai.
• --raw-findings · include all findings regardless of the MVP contract scope
• --upload · send the report to your cloud dashboard · -k, --api-key <key> overrides the env var
• --share · upload and print a shareable report URL

Learning and AI:

• --dismiss "CATEGORY:snippet" · record a false-positive dismissal. After 3 dismissals the learned profile suppresses the finding.
• --no-ai · heuristics only. Free, offline, faster — the recommended CI mode. Without an ANTHROPIC_API_KEY the engine runs deterministic-only regardless.
• --budget <usd> · cap AI spend per run. Default: 1.00.
• --agentic · add a tool-using review pass after the primary analysis. Tune with --reasoning standard|deep, --stream, --advisor-validation.
• --timeout <seconds> · hard timeout. Default 300, max 600.

Examples:

# fast, deterministic, JSON to a file
codetitan analyze . --no-ai --format json --output report.json

# diff-aware CI gate
codetitan analyze . --changed-only --fail-on high

# SBOM export (CycloneDX / SPDX)
codetitan analyze . --no-ai --format sbom --output sbom.json

# cold-audit a public repo without cloning it yourself
codetitan analyze --public vercel/next.js

§ 02 · fix

Preview and apply fixes for auto-fixable findings. The safety model: fixes are validated in an isolated git worktree by default — nothing touches your repo until you promote the result after reviewing the diff.

codetitan fix [path] [flags]

• --dry-run · show what would be fixed without applying anything
• --patch-output <file> · write the proposed diff-style preview to a file
• --promote · move validated worktree fixes into the repo · --diff-reviewed acknowledges you read the diff first
• --validate-command <cmd> · run this (your test suite, a build) inside the worktree before promotion
• --direct · unsafe escape hatch: bypass worktree isolation and write deterministic fixes straight into the repo
• --max-fixes <n> · default 10 · --min-confidence default 85 · --level default 6
• --auto-commit · commit each fix · --create-fix-pr · open a GitHub PR with the changes (needs GITHUB_TOKEN)
• Session flags (--session-output, --review-session, --apply-session, …) · save fix proposals as a replayable manifest, review them offline, approve entries one by one, replay later. Run codetitan fix --help for the full set.

# preview as a patch file
codetitan fix . --dry-run --patch-output fixes.patch

# validate in an isolated worktree, run tests there, then promote
codetitan fix . --validate-command "npm test"
codetitan fix . --promote --diff-reviewed

§ 03 · hook

Manage the git pre-commit hook.

codetitan hook install    # install pre-commit hook
codetitan hook uninstall  # remove it
codetitan hook status     # check if installed

• install --level <1-8> · analysis level for the hook. Default: 2.
• install --no-block · show findings but never block the commit
• install --no-prettier · skip the prettier check step (auto-skipped when the project has no prettier config)

§ 04 · explain

Ask AI to explain a finding from your last run in depth — what it is, why it matters, how to fix it. Address findings by index or by partial rule name.

codetitan analyze . --no-ai     # run first
codetitan explain 3             # explain finding #3 from that run
codetitan explain SQL_INJECTION # or by partial rule name

§ 05 · init

Set up CodeTitan for a project: writes .codetitan.yml and .codetitanignore, and offers to install the pre-commit hook and a CI workflow. -y accepts all defaults without prompting.

codetitan init -y

The generated config:

# CodeTitan configuration

version: 1

analysis:
  level: 4
  languages:
    - javascript
    - typescript

ignore:
  - node_modules/
  - dist/
  - build/
  - .next/
  - coverage/

rules:
  # Add custom YAML rules here or reference rule files:
  # - .codetitan/rules/custom.yml
  severity_threshold: MEDIUM

output:
  format: console  # console | json | markdown | sarif
  # fail_on: high  # exit 1 if findings at this level or above

§ 06 · badge

Generate a README status badge from your last analysis run.

codetitan badge                      # codetitan-badge.svg
codetitan badge --format markdown    # svg | shields | markdown

The hosted badge endpoint that serves a live shield is on the roadmap; the command and local output exist today.

§ 07 · rules

Manage custom security rules — your own YAML rules in .codetitan.yml or .codetitan/rules/. The built-in 266-rule catalog is documented on the rules page.

codetitan rules list          # list custom rules
codetitan rules add my.yml    # validate + register a YAML rule file
codetitan rules test my.yml   # test a rule against a code file

§ 08 · The rest of the binary

• login / logout / whoami · authenticate with your API key, clear it, see who you are
• config · interactive configuration and model selection
• projects / keys / usage · manage cloud projects and API keys, view usage. Local analysis is unmetered; usage says so.
• report · historical trend analysis for the current project
• insights · AI attribution, per-tool quality scores, derived PR risk
• replay <runId> / compare <runA> <runB> · replay or diff persisted local analysis runs
• review / security-review · shared-runtime review passes over a file or directory
• agents · inspect local agent runtime history

§ 09 · Environment variables

• CODETITAN_API_KEY · API key for cloud features (upload, share, dashboard). -k overrides it per run.
• CODETITAN_API_URL · override the API base URL
• ANTHROPIC_API_KEY · your own Anthropic key, required for AI mode. Without it the engine is deterministic-only.
• GITHUB_TOKEN · required by fix --create-fix-pr

§ 10 · Exit codes

• 0 · clean — no findings at or above the gate
• 1 · findings at or above --fail-on, the --risk-threshold was met, or a fatal error (bad flags, unsupported path)

That is the whole contract: zero or one. Gate CI on the exit code plus --fail-on.

§ 11 · Config file

.codetitan.yml lives at the repo root (see § 05 for the generated default). CLI flags override file settings. .codetitanignore works like a .gitignore for the scanner.