CLI Reference

Complete reference for Harness Engineering CLI commands, options, and usage.

Command Structure

All Harness Engineering CLI commands follow this structure:

harness [global-options] <command> [command-options]

Global Options

These options are available for all commands:

--config, -c <path>     Path to harness.config.json
--json                  Output results as JSON
--verbose               Enable verbose output
--quiet                 Suppress non-error output

Examples

# Use custom config file
harness validate --config=./custom/harness.config.json

# Get verbose output
harness validate --verbose

# Output as JSON for scripting
harness validate --json

Setup and Environment Commands

harness setup

Configure the harness environment in one step: generates global slash commands, sets up MCP server for detected AI clients, and configures peer integrations.

harness setup

Examples:

# Run interactive setup
harness setup

harness doctor

Check environment health: Node version, slash command installation, and MCP configuration for all detected AI clients.

harness doctor

Examples:

# Run environment health checks
harness doctor

# Output as JSON
harness doctor --json

Project Commands

harness init

Initialize a new Harness Engineering project.

harness init [options]

Options:

-n, --name <name>       Project name
-l, --level <level>     Adoption level (basic, intermediate, load-bearing-minimum, advanced)
--framework <overlay>   Framework overlay (e.g., nextjs)
--language <lang>       Target language (typescript, python, go, rust, java)
-f, --force             Overwrite existing files
-y, --yes               Use defaults without prompting

Examples:

# Initialize with defaults (interactive)
harness init

# Initialize with a specific name and level
harness init --name my-project --level advanced

# Non-interactive, overwrite existing
harness init --name my-project --yes --force

harness validate

Run all validation checks on the project.

harness validate [options]

Options:

--cross-check           Run cross-artifact consistency validation
--agent-configs         Validate agent configs (CLAUDE.md, hooks, skills) via agnix or built-in fallback rules
--strict                Treat warnings as errors (applies to --agent-configs)
--agnix-bin <path>      Override the agnix binary path discovered on PATH
--severity <level>      Minimum severity that fails the command (error, warning, info)

Exit codes: 0 all applicable checks ran and passed · 1 a check ran and failed · 3 a check could not run (the report is incomplete). See Exit Codes.

Examples:

# Run all validation checks
harness validate

# Run with cross-check validation
harness validate --cross-check

# Validate agent configs with strict mode
harness validate --agent-configs --strict

# Output results as JSON
harness validate --json

harness check-deps

Validate dependency layers and detect circular dependencies.

harness check-deps

Examples:

# Check for dependency issues
harness check-deps

# Verbose output for debugging
harness check-deps --verbose

harness check-docs

Check documentation coverage across the project.

harness check-docs [options]

Options:

--min-coverage <percent>   Minimum required documentation coverage (0-100)

Examples:

# Check documentation coverage
harness check-docs

# Require at least 80% coverage
harness check-docs --min-coverage 80

harness check-phase-gate

Verify that implementation files have matching spec documents.

harness check-phase-gate

Examples:

# Verify phase gate compliance
harness check-phase-gate

harness check-arch

Check architecture assertions against baseline and thresholds. Detects regressions in circular dependencies, layer violations, complexity, coupling, forbidden imports, module size, and dependency depth.

harness check-arch [options]

Options:

--update-baseline       Capture current state as the new baseline
--module <path>         Check a single module only

Examples:

# Check architecture assertions
harness check-arch

# Update baseline to current state
harness check-arch --update-baseline

# Check a single module
harness check-arch --module src/services

# Output as JSON
harness check-arch --json

harness check-perf

Run performance checks: structural complexity, coupling metrics, and size budgets.

harness check-perf [options]

Options:

--structural            Run structural complexity checks only
--coupling              Run coupling metric checks only
--size                  Run size budget checks only

Examples:

# Run all performance checks
harness check-perf

# Run only structural complexity checks
harness check-perf --structural

# Output as JSON
harness check-perf --json

harness check-security

Run lightweight security scan: secrets, injection, XSS, and weak crypto detection.

harness check-security [options]

Options:

--severity <level>      Minimum severity threshold (default: warning)
--changed-only          Only scan git-changed files

Examples:

# Run full security scan
harness check-security

# Scan only changed files at error severity
harness check-security --changed-only --severity error

harness add

Add a component to the project.

harness add <type> <name>

Types:

layer          Add a new architectural layer
module         Add a new module
doc            Add a new documentation file
skill          Add a new skill
persona        Add a new persona

Examples:

# Add a new layer
harness add layer data-access

# Add a documentation file
harness add doc api-reference

# Add a module
harness add module user-service

# Add a skill
harness add skill code-review

harness blueprint

Generate a self-contained, interactive HTML blueprint of the codebase including architecture, dependencies, and module structure.

harness blueprint [path]

Arguments:

[path]                   Path to the project root (default: .)

Options:

-o, --output <dir>      Output directory (default: docs/blueprint)

Examples:

# Generate blueprint for current project
harness blueprint

# Generate to a custom output directory
harness blueprint --output ./out/blueprint

# Generate for a specific project path
harness blueprint /path/to/project

harness predict

Predict which architectural constraints will break and when, based on timeline snapshot trends and optional roadmap spec impact.

harness predict [options]

Options:

--category <name>       Filter to a single metric category
--no-roadmap            Baseline only — skip roadmap spec impact analysis
--horizon <weeks>       Forecast horizon in weeks (default: 12)

Examples:

# Predict constraint failures
harness predict

# Predict only for complexity metrics
harness predict --category complexity

# Forecast 24 weeks out, baseline only
harness predict --horizon 24 --no-roadmap

# Output as JSON
harness predict --json

harness recommend

Recommend skills based on codebase health analysis. Analyzes validation results, entropy, documentation coverage, and architecture health to suggest the most impactful skills to run next.

harness recommend [options]

Options:

--no-cache              Force fresh health snapshot (skip cached results)
--top <n>               Maximum number of recommendations (default: 5)

Examples:

# Get skill recommendations
harness recommend

# Force fresh analysis, show top 3
harness recommend --no-cache --top 3

# Output as JSON
harness recommend --json

harness advise-skills

Content-based skill recommendations for a spec. Analyzes a proposal or spec document to identify relevant skills, producing a tiered list of Apply, Reference, and optionally Consider skills. Results are written to a SKILLS.md file alongside the spec.

harness advise-skills [options]

Options:

--spec-path <path>      Path to the spec (proposal.md) (required)
--thorough              Include Consider tier in output
--top <n>               Max skills per tier (default: 5)

Examples:

# Get skill recommendations for a spec
harness advise-skills --spec-path docs/specs/auth-refactor/proposal.md

# Include Consider tier, limit to top 3 per tier
harness advise-skills --spec-path docs/specs/auth-refactor/proposal.md --thorough --top 3

# Output as JSON
harness advise-skills --spec-path docs/specs/auth-refactor/proposal.md --json

Entropy and Drift Commands

harness cleanup

Detect entropy issues such as documentation drift, dead code, and inconsistent patterns.

harness cleanup [options]

Options:

-t, --type <type>       Type of entropy to check (drift, dead-code, patterns, all). Default: all

Examples:

# Detect all entropy issues
harness cleanup

# Check only for documentation drift
harness cleanup --type drift

# Check only for dead code
harness cleanup --type dead-code

harness fix-drift

Auto-fix detected entropy issues including documentation drift and dead code.

harness fix-drift [options]

Options:

--no-dry-run            Apply fixes (default behavior is dry-run)

Examples:

# Preview fixes (dry run)
harness fix-drift

# Apply fixes
harness fix-drift --no-dry-run

harness impact-preview

Show the blast radius of staged changes using the knowledge graph. Groups affected files by category (code, tests, docs) to help assess risk before committing.

harness impact-preview [options]

Options:

--detailed              Show all affected files instead of top items
--per-file              Show impact per staged file instead of aggregate
--path <path>           Project root (default: cwd)

Examples:

# Preview impact of staged changes
harness impact-preview

# Show detailed per-file breakdown
harness impact-preview --detailed --per-file

# Output as JSON
harness impact-preview --json

harness knowledge-pipeline

Run knowledge extraction, drift detection, and gap analysis. Orchestrates a multi-phase pipeline that extracts knowledge from code and documentation, detects drift between sources, identifies gaps, and optionally auto-remediates findings.

harness knowledge-pipeline [options]

Options:

--fix                   Enable convergence-based auto-remediation (default: detect-only)
--ci                    Non-interactive mode — apply safe fixes only, report everything else
--domain <name>         Limit pipeline to a specific knowledge domain
--drift-check           Exit 1 if unresolved drift exists (CI gate mode)
--analyze-images        Enable vision model analysis of image files
--image-paths <paths>   Comma-separated image file paths for analysis
--coverage              Display per-domain coverage report
--check-contradictions  Display cross-source contradiction report

Examples:

# Run knowledge pipeline (detect only)
harness knowledge-pipeline

# Run with auto-remediation
harness knowledge-pipeline --fix

# CI mode with drift gate
harness knowledge-pipeline --ci --drift-check

# Limit to a specific domain with coverage report
harness knowledge-pipeline --domain api --coverage

# Analyze images in the pipeline
harness knowledge-pipeline --analyze-images --image-paths "docs/diagrams/arch.png,docs/diagrams/flow.png"

# Output as JSON
harness knowledge-pipeline --json

harness scan-config

Scan CLAUDE.md, AGENTS.md, .gemini/settings.json, and skill.yaml files for prompt injection patterns and security rule violations.

harness scan-config [options]

Options:

--path <dir>            Target directory to scan (default: cwd)
--fix                   Strip high-severity patterns from files in-place

Examples:

# Scan for prompt injection patterns
harness scan-config

# Scan a specific directory
harness scan-config --path ./my-project

# Auto-fix high-severity patterns
harness scan-config --fix

Snapshot and Timeline Commands

harness snapshot capture

Capture current architecture metrics as a timeline snapshot, recording values for circular deps, layer violations, complexity, coupling, and other metrics.

harness snapshot capture

Examples:

# Capture a snapshot
harness snapshot capture

# Output as JSON
harness snapshot capture --json

harness snapshot list

List all captured architecture snapshots.

harness snapshot list

Examples:

# List snapshots
harness snapshot list

# Output as JSON
harness snapshot list --json

harness snapshot trends

Show architecture metric trends over time based on captured snapshots.

harness snapshot trends [options]

Options:

--last <n>              Number of recent snapshots to analyze (default: 10)
--since <date>          Show trends since an ISO date

Examples:

# Show trends from recent snapshots
harness snapshot trends

# Show trends from the last 20 snapshots
harness snapshot trends --last 20

# Show trends since a specific date
harness snapshot trends --since 2026-01-01

Agent Commands

harness agent run

Run an agent task.

harness agent run [task] [options]

Arguments:

[task]                  Task to run (review, doc-review, test-review)

Options:

--timeout <ms>          Timeout in milliseconds (default: 300000)
--persona <name>        Run a persona by name
--trigger <context>     Trigger context (auto, on_pr, on_commit, manual). Default: auto

Examples:

# Run an agent task
harness agent run

# Run with a specific persona and timeout
harness agent run --persona architect --timeout 60000

harness agent review

Run unified code review pipeline on current changes.

harness agent review [options]

Options:

--comment               Post inline comments to GitHub PR
--ci                    Enable eligibility gate, non-interactive output
--deep                  Add threat modeling pass to security agent
--no-mechanical         Skip mechanical checks
--thorough              Generate task-specific rubric before reading implementation
--isolated              Two-stage review: spec-compliance then code-quality with disjoint context

Examples:

# Review current changes
harness agent review

# CI mode with deep security analysis
harness agent review --ci --deep

# Post comments to GitHub PR
harness agent review --comment

harness orchestrator run

Run the orchestrator daemon, which coordinates multi-agent workflows defined in a harness.orchestrator.md file.

harness orchestrator run [options]

Options:

-w, --workflow <path>   Path to harness.orchestrator.md (default: harness.orchestrator.md)
--headless              Run without TUI (server-only mode for use with web dashboard)

Examples:

# Run the orchestrator with default workflow
harness orchestrator run

# Run with a custom workflow file
harness orchestrator run --workflow ./workflows/deploy.md

Taint Commands

Manage sentinel session taint state. When the sentinel hook detects risky operations, it taints the session to block further destructive operations until cleared.

harness taint status

Show current taint status for a session or all sessions.

harness taint status [sessionId]

Arguments:

[sessionId]             Specific session ID to check (default: all sessions)

Examples:

# Show taint status for all sessions
harness taint status

# Show taint status for a specific session
harness taint status my-session-id

harness taint clear

Clear session taint, removing taint files and re-enabling destructive operations.

harness taint clear [sessionId]

Arguments:

[sessionId]             Specific session ID to clear (default: all sessions)

Examples:

# Clear all taint
harness taint clear

# Clear taint for a specific session
harness taint clear my-session-id

Persona Commands

harness persona list

List available agent personas.

harness persona list

harness persona generate

Generate artifacts from a persona configuration.

harness persona generate <name> [options]

Options:

--output-dir <dir>      Output directory for generated artifacts
--only <type>           Generate only a specific artifact type (ci, agents-md, runtime)

Examples:

# Generate all artifacts for a persona
harness persona generate architect

# Generate only CI workflow to a custom directory
harness persona generate architect --only ci --output-dir ./out

# Generate only AGENTS.md fragment
harness persona generate architect --only agents-md

# Generate only runtime config
harness persona generate architect --only runtime

Skill Commands

harness skill list

List available skills.

harness skill list [options]

Options:

--installed             Show only community-installed skills
--local                 Show only project-local skills
--all                   Show all skills (default)

harness skill run

Run a skill, outputting SKILL.md content with a context preamble.

harness skill run <name> [options]

Options:

--path <path>           Project root path for context injection
--complexity <level>    Rigor level: fast, standard, thorough (default: standard)
--phase <name>          Start at a specific phase (for re-entry)
--party                 Enable multi-perspective evaluation

Examples:

# Run a skill
harness skill run code-review

# Run with complexity and phase context
harness skill run implementation --complexity thorough --phase build

harness skill validate

Validate all skill.yaml files and SKILL.md structure.

harness skill validate

harness skill info

Show metadata for a specific skill.

harness skill info <name>

Examples:

# Show info about a skill
harness skill info code-review

harness create-skill

Scaffold a new skill with skill.yaml and SKILL.md files.

harness create-skill <path> [options]

Options:

--name <name>           Skill name
--description <desc>    Skill description
--cognitive-mode <mode> Cognitive mode for the skill
--reads <files>         Files the skill reads
--produces <files>      Files the skill produces
--pre-checks <checks>   Pre-check commands
--post-checks <checks>  Post-check commands

Examples:

# Scaffold a new skill
harness create-skill ./skills/my-skill --name my-skill --description "Does a thing"

# Scaffold with full metadata
harness create-skill ./skills/review \
  --name review \
  --cognitive-mode analytical \
  --reads "src/**/*.ts" \
  --produces "reports/review.md"

Skill Marketplace Commands

harness install

Install a community skill from the @harness-skills/* npm registry.

harness install <skill> [options]

Option	Description
`--version <range>`	Semver range or exact version (default: latest)
`--force`	Force reinstall even if same version is already installed
`--from <path>`	Install from a local directory or .tgz file
`--registry <url>`	Use a custom npm registry URL

Skills are placed in agents/skills/community/{platform}/ and tracked in skills-lock.json. Dependencies listed in depends_on are auto-installed.

Examples

# Install latest version
harness install deployment

# Install specific version range
harness install deployment --version "^1.0.0"

# Force reinstall
harness install deployment --force

harness uninstall

Remove a community-installed skill.

harness uninstall <skill> [options]

Option	Description
`--force`	Remove even if other skills depend on this one

Examples

# Uninstall a skill
harness uninstall deployment

# Force remove despite dependents
harness uninstall docker-basics --force

harness skill search

Search for community skills on the npm registry.

harness skill search <query> [options]

Option	Description
`--platform <platform>`	Filter by platform (e.g., claude-code, gemini-cli)
`--trigger <trigger>`	Filter by trigger type (e.g., manual, automatic)
`--registry <url>`	Use a custom npm registry URL

Examples

# Search for deployment skills
harness skill search deploy

# Filter by platform
harness skill search auth --platform claude-code

harness skill create

Scaffold a new community skill with skill.yaml, SKILL.md, and README.md.

harness skill create <name> [options]

Option	Description
`--description <desc>`	Skill description
`--type <type>`	Skill type: rigid or flexible (default: flexible)
`--platforms <list>`	Comma-separated platforms (default: claude-code)
`--triggers <list>`	Comma-separated triggers (default: manual)
`--output-dir <dir>`	Output directory

Examples

# Create a basic skill
harness skill create my-deploy --description "Deploy to production"

# Create with options
harness skill create ci-helper --type rigid --platforms "claude-code,gemini-cli"

harness skill publish

Validate and publish a skill to the @harness-skills/* namespace on npm.

harness skill publish [options]

Option	Description
`--dry-run`	Run validation and generate package.json without publishing
`--dir <dir>`	Skill directory (default: current directory)
`--registry <url>`	Use a custom npm registry URL

Runs a 6-check pre-publish validation pipeline: schema validation, required fields, SKILL.md sections, version bump, name guard, dependency check.

Examples

# Dry run to check validation
harness skill publish --dry-run

# Publish from a specific directory
harness skill publish --dir ./my-skill

Constraint Sharing Commands

harness share

Extract and publish a constraints bundle from constraints.yaml. Packages your architecture constraints (layers, dependency rules, thresholds) into a portable .harness-constraints.json file that other projects can install.

harness share [path]

Arguments:

[path]                   Path to the project root (default: .)

Options:

-o, --output <dir>      Output directory for the bundle (default: .)

Examples:

# Extract constraints bundle from current project
harness share

# Output bundle to a specific directory
harness share --output ./dist

# Share from a specific project
harness share /path/to/project

harness install-constraints

Install a constraints bundle into the local harness config. Merges layers, dependency rules, and thresholds from a .harness-constraints.json file into harness.config.json.

harness install-constraints <source>

Arguments:

<source>                Path to a .harness-constraints.json bundle file

Options:

--force-local           Resolve all conflicts by keeping local values
--force-package         Resolve all conflicts by using package values
--dry-run               Show what would change without writing files
-c, --config <path>     Path to harness.config.json

Examples:

# Install constraints from a bundle
harness install-constraints ./team-standards.harness-constraints.json

# Preview changes without applying
harness install-constraints ./standards.harness-constraints.json --dry-run

# Force package values on conflict
harness install-constraints ./standards.harness-constraints.json --force-package

harness uninstall-constraints

Remove a previously installed constraints package, reverting the config sections it contributed.

harness uninstall-constraints <name>

Arguments:

<name>                  Name of the constraint package to uninstall

Options:

-c, --config <path>     Path to harness.config.json

Examples:

# Uninstall a constraints package
harness uninstall-constraints team-standards

Linter Commands

harness linter generate

Generate ESLint rules from a harness-linter.yml configuration.

harness linter generate [options]

Options:

-c, --config <path>     Path to harness-linter.yml config
-o, --output <dir>      Output directory for generated rules
--clean                 Remove existing generated rules before generating
--dry-run               Preview what would be generated without writing files
--json                  Output results as JSON
--verbose               Verbose output

Examples:

# Generate rules from default config
harness linter generate

# Generate with custom config and output directory
harness linter generate --config ./my-linter.yml --output ./eslint-rules

# Preview without writing
harness linter generate --dry-run

harness linter validate

Validate a harness-linter.yml configuration file.

harness linter validate [options]

Options:

-c, --config <path>     Path to harness-linter.yml config
--json                  Output results as JSON

Examples:

# Validate default config
harness linter validate

# Validate a specific config file
harness linter validate --config ./my-linter.yml

State Commands

harness state show

Show current project state.

harness state show [options]

Options:

--path <path>           Project root path
--stream <name>         Target a specific stream

harness state reset

Reset project state.

harness state reset [options]

Options:

--path <path>           Project root path
--stream <name>         Target a specific stream
--yes                   Skip confirmation prompt

Examples:

# Reset state (with confirmation)
harness state reset

# Reset without confirmation
harness state reset --yes

harness state learn

Append a learning to .harness/learnings.md.

harness state learn <message> [options]

Options:

--path <path>           Project root path
--stream <name>         Target a specific stream

Examples:

# Record a learning
harness state learn "Circular deps in data layer resolved by extracting interfaces"

harness state streams

Manage state streams. Streams allow multiple parallel workstreams to track state independently.

harness state streams

Learnings Commands

harness learnings prune

Analyze global learnings for patterns, present improvement proposals, and archive old entries.

harness learnings prune [options]

Options:

--path <path>           Project root path (default: .)
--stream <name>         Target a specific stream

Examples:

# Prune and consolidate learnings
harness learnings prune

# Prune a specific stream
harness learnings prune --stream feature-auth

Usage and Cost Tracking Commands

harness usage sessions

List recent sessions with token usage and cost.

harness usage sessions [options]

Options:

--limit <n>             Number of sessions to show (default: 10, max: 100)

Examples:

# List recent sessions
harness usage sessions

# Show last 25 sessions
harness usage sessions --limit 25

# Output as JSON
harness usage sessions --json

harness usage session

Show detailed token breakdown for a specific session.

harness usage session <id>

Arguments:

<id>                    Session ID

Examples:

# Show details for a session
harness usage session abc123

harness usage daily

Show per-day token usage and cost.

harness usage daily [options]

Options:

--days <n>              Number of days to show (default: 7, max: 90)

Examples:

# Show last 7 days of usage
harness usage daily

# Show last 30 days
harness usage daily --days 30

# Output as JSON
harness usage daily --json

harness usage latest

Show the most recently completed session cost summary.

harness usage latest

Examples:

# Show latest session cost
harness usage latest

Integration Commands

harness mcp

Start the MCP (Model Context Protocol) server on stdio. Used by AI clients (Claude Code, Gemini CLI, Cursor) to access harness tools programmatically.

harness mcp [options]

Options:

--tools <tools...>      Only register the specified tools (used by Cursor integration)
--tier <tier>           Load a preset tool tier instead of all tools (core, standard, full)
--budget-tokens <n>     Auto-select tier to fit this baseline token budget

Examples:

# Start MCP server with all tools
harness mcp

# Start with only specific tools
harness mcp --tools validate check-docs scan

# Start with a specific tier
harness mcp --tier core

# Auto-select tier based on token budget
harness mcp --budget-tokens 50000

harness setup-mcp

Configure MCP server for AI agent integration.

harness setup-mcp [options]

Options:

--client <client>       Client to configure (claude, gemini, codex, cursor, all). Default: all
--pick                  Launch interactive tool picker (Cursor only)
--yes                   Bypass interactive picker and use curated 25-tool set (Cursor only)

Examples:

# Set up MCP integration for all clients
harness setup-mcp

# Set up for a specific client
harness setup-mcp --client claude

harness integrations list

Show all MCP peer integrations and their current status (enabled, available, dismissed).

The suggested catalog is curated for currency. As of the latest review it contains:

Tier 0 (zero-config): context7 (live library docs), playwright (browser/E2E automation), harness (harness's own code-intelligence + workflow MCP: code_search, ask_graph, review_changes, outcome_eval).
Tier 1 (API key required): github (official GitHub MCP, GITHUB_PERSONAL_ACCESS_TOKEN), exa (structured agent web search, EXA_API_KEY).

Each entry carries a lastReviewed date and the catalog exposes CATALOG_LAST_REVIEWED; harness doctor emits a non-blocking advisory once the catalog is stale so the suggested set signals its own age.

harness integrations list

Examples:

# List all integrations
harness integrations list

harness integrations add

Enable an MCP peer integration by adding its configuration to your MCP settings.

harness integrations add <name>

Arguments:

<name>                  Integration name (e.g., exa, github)

Examples:

# Enable the Exa search integration
harness integrations add exa

harness integrations remove

Remove an MCP peer integration from your configuration.

harness integrations remove <name>

Arguments:

<name>                  Integration name (e.g., exa, github)

Examples:

# Remove an integration
harness integrations remove exa

harness integrations dismiss

Suppress doctor recommendations for an integration you do not want to use.

harness integrations dismiss <name>

Arguments:

<name>                  Integration name (e.g., exa, github)

Examples:

# Dismiss integration recommendation
harness integrations dismiss github

harness generate-slash-commands

Generate native slash commands for Claude Code, Gemini CLI, Codex CLI, and Cursor from skill metadata.

harness generate-slash-commands [options]

Options:

--platforms <platforms>  Target platforms (comma-separated)
--global                Install commands globally
--include-global        Include built-in global skills alongside project skills
--output <dir>          Output directory
--skills-dir <dir>      Directory containing skills
--dry-run               Preview without writing files
--yes                   Skip confirmation prompts

Examples:

# Generate slash commands for all platforms
harness generate-slash-commands

# Generate only for Claude Code, dry run
harness generate-slash-commands --platforms claude-code --dry-run

# Generate globally with custom skills directory
harness generate-slash-commands --global --skills-dir ./my-skills

Generation Commands

harness generate-agent-definitions

Generate agent definition files from personas for Claude Code and Gemini CLI.

harness generate-agent-definitions [options]

Options:

--platforms <list>       Target platforms (comma-separated, default: claude-code,gemini-cli)
--global                 Write to global agent directories
--output <dir>           Custom output directory
--dry-run                Show what would change without writing

Examples:

# Generate agent definitions for all platforms
harness generate-agent-definitions

# Preview without writing
harness generate-agent-definitions --dry-run

# Generate only for Claude Code
harness generate-agent-definitions --platforms claude-code

harness generate

Generate all platform integrations (slash commands + agent definitions).

harness generate [options]

Options:

--platforms <list>       Target platforms (comma-separated, default: claude-code,gemini-cli)
--global                 Write to global directories
--include-global         Include built-in global skills
--output <dir>           Custom output directory
--dry-run                Show what would change without writing
--yes                    Skip deletion confirmation prompts

Examples:

# Generate all integrations
harness generate

# Generate globally with dry run
harness generate --global --dry-run

Dashboard Command

harness dashboard

Start the Harness local web dashboard, providing a visual overview of project health, architecture metrics, entropy analysis, and more.

harness dashboard [options]

Options:

--port <port>           Client dev server port (default: 3700)
--api-port <port>       API server port (default: 3701)
--orchestrator-url <url>  Orchestrator URL (default: http://localhost:8080)
--no-open               Do not automatically open browser
--cwd <path>            Project directory (defaults to cwd)

Examples:

# Start dashboard with defaults
harness dashboard

# Start on custom ports without opening browser
harness dashboard --port 4000 --api-port 4001 --no-open

# Start for a specific project
harness dashboard --cwd /path/to/project

CI/CD Commands

harness ci check

Run all harness checks for CI (validate, deps, docs, entropy, phase-gate, arch).

harness ci check [options]

Options:

--skip <checks>          Comma-separated checks to skip (e.g., entropy,docs)
--fail-on <severity>     Fail on severity level: error (default) or warning

Examples:

# Run all CI checks
harness ci check

# Skip entropy and docs checks
harness ci check --skip entropy,docs

# Fail on warnings too
harness ci check --fail-on warning

harness ci init

Generate CI configuration for harness checks.

harness ci init [options]

Options:

--platform <platform>    CI platform: github, gitlab, or generic
--checks <list>          Comma-separated list of checks to include

Examples:

# Generate GitHub Actions workflow
harness ci init --platform github

# Generate with specific checks
harness ci init --platform gitlab --checks validate,deps,docs

Performance Commands

harness perf bench

Run benchmarks via vitest bench.

harness perf bench [glob]

Arguments:

[glob]                   Glob pattern to filter benchmark files

Examples:

# Run all benchmarks
harness perf bench

# Run benchmarks matching a pattern
harness perf bench "src/**/*.bench.ts"

harness perf baselines

Manage performance baselines (show, update, compare).

harness perf baselines

harness perf critical-paths

Show resolved critical path set from annotations and graph inference.

harness perf critical-paths

harness perf report

Generate a full performance report with metrics, trends, and hotspots.

harness perf report

Update Command

harness update

Update all @harness-engineering packages to the latest version.

harness update [options]

Options:

--version <semver>       Pin @harness-engineering/cli to a specific version

Examples:

# Update to latest
harness update

# Pin to a specific version
harness update --version 1.5.0

Graph Commands

harness scan

Scan project and build knowledge graph.

harness scan [path]

Arguments:

[path]                   Project root path (default: .)

Examples:

# Scan current project
harness scan

# Scan a specific path
harness scan /path/to/project

harness ingest

Ingest data into the knowledge graph.

harness ingest [options]

Options:

--source <name>          Source to ingest: code, knowledge, git, business-signals, jira, slack, ci, confluence
--all                    Run all sources (code, knowledge, git, and configured connectors)
--full                   Force full re-ingestion

Examples:

# Ingest code structure
harness ingest --source code

# Ingest all sources
harness ingest --all

# Force full re-ingestion
harness ingest --all --full

harness query

Query the knowledge graph.

harness query <rootNodeId> [options]

Arguments:

<rootNodeId>             Starting node ID (required)

Options:

--depth <n>              Max traversal depth (default: 3)
--types <types>          Comma-separated node types to include
--edges <edges>          Comma-separated edge types to include
--bidirectional          Traverse both directions

Examples:

# Query from a specific node
harness query src/services/user-service.ts

# Query with depth and type filters
harness query src/index.ts --depth 5 --types file,function --edges imports

harness graph status

Show knowledge graph statistics.

harness graph status

harness graph export

Export the knowledge graph.

harness graph export [options]

Options:

--format <format>        Output format: json or mermaid (required)

Examples:

# Export as JSON
harness graph export --format json

# Export as Mermaid diagram
harness graph export --format mermaid

harness traceability

Show spec-to-implementation traceability from the knowledge graph. Maps requirements from spec documents to their implementing code files and tests, showing coverage status and confidence levels.

harness traceability [options]

Options:

--spec <path>           Filter by spec file path
--feature <name>        Filter by feature name

Examples:

# Show traceability for all specs
harness traceability

# Filter by a specific spec file
harness traceability --spec docs/specs/auth-refactor/proposal.md

# Filter by feature name
harness traceability --feature "User Authentication"

# Output as JSON
harness traceability --json

Hooks Commands

harness hooks init

Install Claude Code hook configurations into the current project. Copies hook scripts to .harness/hooks/ and merges hook entries into .claude/settings.json.

harness hooks init [options]

Options:

--profile <profile>      Hook profile: minimal, standard, or strict (default: standard)

Profiles:

minimal — Safety floor: block-no-verify
standard — Balanced enforcement (default): all minimal hooks plus protect-config, quality-warner, pre-compact-state, adoption-tracker, telemetry-reporter
strict — Full enforcement: all standard hooks plus strict-quality-gate, cost-tracker, sentinel-pre, sentinel-post

Examples:

# Install with default (standard) profile
harness hooks init

# Install strict profile
harness hooks init --profile strict

# Output as JSON
harness hooks init --json

harness hooks list

Show installed hooks and the active profile.

harness hooks list

Examples:

# List installed hooks
harness hooks list

# List as JSON
harness hooks list --json

harness hooks add

Add a single hook without changing the active profile.

harness hooks add <hook-name>

Arguments:

<hook-name>              Hook name or alias (e.g., sentinel)

Examples:

# Add a specific hook
harness hooks add sentinel

harness hooks remove

Remove all harness-managed hooks from the current project. Deletes .harness/hooks/ and cleans hook entries from .claude/settings.json.

harness hooks remove

Examples:

# Remove all harness hooks
harness hooks remove

# Remove and get JSON output
harness hooks remove --json

Adoption Commands

harness adoption skills

Show top skills by invocation count from local adoption telemetry.

harness adoption skills [options]

Options:

--limit <n>             Number of skills to show (default: 20)

Examples:

# Show top skills by invocation count
harness adoption skills

# Show top 10 skills
harness adoption skills --limit 10

# Output as JSON
harness adoption skills --json

harness adoption recent

Show recent skill invocations sorted by date.

harness adoption recent [options]

Options:

--limit <n>             Number of invocations to show (default: 20)

Examples:

# Show recent skill invocations
harness adoption recent

# Show last 50 invocations
harness adoption recent --limit 50

# Output as JSON
harness adoption recent --json

harness adoption skill

Show detailed adoption data for a specific skill, including phase completion rates and outcome breakdown.

harness adoption skill <name>

Arguments:

<name>                  Skill name to inspect

Examples:

# Show detail for a specific skill
harness adoption skill code-review

# Output as JSON
harness adoption skill code-review --json

Protected Region Commands

harness audit-protected

Report all harness-ignore protected code regions across the project. Scans source files for protection annotations and reports any annotation issues.

harness audit-protected

Examples:

# Audit all protected regions
harness audit-protected

# Output as JSON
harness audit-protected --json

Session Management Commands

harness cleanup-sessions

Remove stale session directories from .harness/sessions/ that have had no writes in the last 24 hours.

harness cleanup-sessions [options]

Options:

--dry-run               List stale sessions without deleting them
--path <path>           Project root path (default: .)

Examples:

# Remove stale sessions
harness cleanup-sessions

# Preview which sessions would be removed
harness cleanup-sessions --dry-run

# Clean sessions for a specific project
harness cleanup-sessions --path /path/to/project

# Output as JSON
harness cleanup-sessions --json

Analysis Sync Commands

harness publish-analyses

Publish locally generated intelligence analyses to the external issue tracker (e.g., GitHub). Reads analyses from .harness/analyses/ and posts them as comments on matching roadmap issues.

harness publish-analyses [options]

Options:

-d, --dir <path>        Workspace directory (default: cwd)

Requires:

GITHUB_TOKEN environment variable (or .env file in project root)
tracker configuration in harness.config.json
docs/roadmap.md with externalId fields on features

Examples:

# Publish analyses to GitHub issues
harness publish-analyses

# Publish from a specific workspace
harness publish-analyses --dir /path/to/project

harness sync-analyses

Pull published intelligence analyses from the external issue tracker into the local .harness/analyses/ directory. Scans issue comments for embedded analysis records.

harness sync-analyses [options]

Options:

-d, --dir <path>        Workspace directory (default: cwd)

Requires:

GITHUB_TOKEN environment variable (or .env file in project root)
tracker configuration in harness.config.json
docs/roadmap.md with externalId fields on features

Examples:

# Sync analyses from GitHub issues
harness sync-analyses

# Sync from a specific workspace
harness sync-analyses --dir /path/to/project

Telemetry Commands

harness telemetry identify

Set or clear telemetry identity fields in .harness/telemetry.json. Identity fields tag telemetry data with project, team, or alias for filtering.

harness telemetry identify [options]

Options:

--project <name>        Project name
--team <name>           Team name
--alias <name>          User alias
--clear                 Remove all identity fields

Examples:

# Set project and team identity
harness telemetry identify --project my-app --team platform

# Set alias
harness telemetry identify --alias jdoe

# Clear all identity fields
harness telemetry identify --clear

harness telemetry status

Show current telemetry consent state, install ID, identity, and environment variable overrides.

harness telemetry status [options]

Options:

--json                  Output as JSON

Examples:

# Show telemetry status
harness telemetry status

# Output as JSON
harness telemetry status --json

harness telemetry test

Send a test event to PostHog and verify connectivity. Requires telemetry to be enabled.

harness telemetry test

Examples:

# Send a test telemetry event
harness telemetry test

harness telemetry-wizard

Interactive wizard that walks through telemetry configuration: anonymous telemetry opt-in, local adoption tracking opt-in, and optional identity fields. Writes results to harness.config.json and .harness/telemetry.json.

harness telemetry-wizard

Note: This wizard runs automatically during harness setup if telemetry is not yet configured. It requires an interactive TTY session.

Examples:

# Run the telemetry configuration wizard
harness telemetry-wizard

Exit Codes

The CLI uses the following exit codes:

0       Success
1       Validation failed
2       General error
3       Zero denominator - the command ran but examined nothing

Exit code 3 means a check abstained: it ran but had nothing to examine, or its input existed and could not be consumed. It is distinct from 0 (nothing was verified) and from 2 (nothing malfunctioned). A gate that matched, compared, or fetched zero items has abstained, not passed, and must never read as green. harness validate, harness roadmap sync, harness check-docs, harness check-deployment, and harness review-ci all use it.

For harness validate specifically the three codes map to the three possible states of a run:

Code	Meaning
`0`	Every applicable check ran and passed.
`1`	A check ran and failed.
`3`	A check could not run — the report is incomplete. Listed under "Checks that could not run".

Abstention outranks failure: a run with both an unavailable check and error findings exits 3, because exit 1 would imply the reported findings are the complete list. --severity never filters unavailableChecks.

In --json mode the same information appears as complete: false and a populated unavailableChecks array. Read complete (or the exit code), not valid. valid reports only on checks that actually ran, so it stays true when a check abstained — harness validate --json | jq -e .valid is not a sufficient gate. The trustworthy green is complete === true && valid === true, which is exactly what exit code 0 means.

Use exit codes in scripts:

harness validate
if [ $? -ne 0 ]; then
  echo "Validation did not pass"
  exit 1
fi

Troubleshooting

Command Not Recognized

Ensure the CLI is installed and in your PATH:

npx harness --help
which harness

Configuration Not Found

Specify the config path explicitly:

harness validate --config=/path/to/harness.config.json

Uh oh!

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI Reference

Command Structure

Global Options

Examples

Setup and Environment Commands

harness setup

harness doctor

Project Commands

harness init

harness validate

harness check-deps

harness check-docs

harness check-phase-gate

harness check-arch

harness check-perf

harness check-security

harness add

harness blueprint

harness predict

harness recommend

harness advise-skills

Entropy and Drift Commands

harness cleanup

harness fix-drift

harness impact-preview

harness knowledge-pipeline

harness scan-config

Snapshot and Timeline Commands

harness snapshot capture

harness snapshot list

harness snapshot trends

Agent Commands

harness agent run

harness agent review

harness orchestrator run

Taint Commands

harness taint status

harness taint clear

Persona Commands

harness persona list

harness persona generate

Skill Commands

harness skill list

harness skill run

harness skill validate

harness skill info

harness create-skill

Skill Marketplace Commands

harness install

Examples

harness uninstall

Examples

harness skill search

Examples

harness skill create

Examples

harness skill publish

Examples

Constraint Sharing Commands

harness share

harness install-constraints

harness uninstall-constraints

Linter Commands

harness linter generate

harness linter validate

State Commands

harness state show

harness state reset

harness state learn

harness state streams

Learnings Commands

harness learnings prune

Usage and Cost Tracking Commands