Harness CLI

harness-cli

A thin agent-facing guide for the harness CLI shipped by the agent-harness-skills package. The CLI exposes 17 subcommands in six categories and supports --then pipeline composition for single-invocation workflows.

The detailed per-command reference lives in references/COMMANDS.md. Pipeline recipes live in references/PIPELINES.md. Output format conventions live in references/OUTPUT-FORMATS.md.

Installation

# uv is the canonical installer
curl -LsSf https://astral.sh/uv/install.sh | sh   # if not already installed
uv tool install agent-harness-skills

harness --help        # confirm install
harness --version

The package registers a harness script via [project.scripts] in pyproject.toml (harness = "harness_skills.cli.main:cli"). Python 3.12+ is required; uv will provision a suitable interpreter automatically.

Command map

Pick the category that matches the task, then open references/COMMANDS.md for the specific subcommand's flags and outputs.

If you can't tell which command to reach for, run harness --help and skim the one-line summaries — every subcommand also has its own harness <cmd> --help.

Choosing the right entry point

Use this decision flow before invoking anything. Most failures come from running the wrong subcommand, not from flag mistakes.

1. No harness.config.yaml or harness_manifest.json in the repo? → Start with harness create. This bootstraps the configuration and generates initial artifacts.
2. Config exists, code has drifted? → harness update performs a three-way merge so hand-edits are preserved.
3. About to claim work is done? → harness evaluate runs the full gate suite. For a single targeted gate use harness lint --gate <name>.
4. Working through a multi-step task? → harness plan writes the plan, harness status shows progress, harness resume rehydrates state when an agent hands off, and harness completion-report aggregates final status.
5. Need an isolated server for an agent worktree? → harness boot (per-worktree port + optional DB isolation + health check).
6. Need to look something up across the codebase? → harness search (uses the indexed symbol table; faster than grep for symbol-shaped queries).

Pipeline composition with --then

Any subcommand chain can be expressed as a single invocation:

# scaffold, then gate, then run all evaluations
harness create --then lint --then evaluate

# per-stage flags work as expected
harness create --profile standard --then lint --gate architecture

Semantics:

• Stages run in order; a non-zero exit code aborts the remainder.
• A trailing --then with no following token is silently dropped (safe to programmatically build).
• The exit code of the last successful stage is returned.

More chains in references/PIPELINES.md.

Output formats

Most commands accept --format json|yaml|table:

• table is the default for interactive shells (TTY).
• json is the default when stdout is not a TTY — so CI captures structured output automatically.
• Pass --format json explicitly whenever you intend to parse the result programmatically; do not rely on TTY detection from inside a subagent.

See references/OUTPUT-FORMATS.md for the schema of each command's JSON payload.

Operating principles for agents

These keep invocations cheap and predictable:

• Always prefer --format json in subagents. Table output is decorative and brittle to parse.
• Run harness evaluate before declaring a task done. It is the canonical "are the gates green?" check.
• Use --then rather than spawning multiple shells. It preserves configuration discovery and produces a single audit trail.
• Treat the exit code as ground truth. Non-zero means the gate / step failed; do not paper over it with text inspection.
• Do not edit harness_manifest.json by hand. Regenerate it with harness manifest or harness update — hand edits are blown away on the next scan.

When this skill does not apply

• The user is asking about a different tool whose binary is also called harness (e.g. Drone Harness CI, Cypress harness mode). Confirm the context before triggering — the package name agent-harness-skills and the claude-agent-sdk dependency are reliable disambiguators.
• The user wants to write a new skill, not run the CLI. Use the skill-creator skill instead.
• The user wants to drive the harness via its Python API rather than the CLI. The CLI is a thin wrapper; importing harness_skills directly is fine but out of scope for this skill — point them at harness_skills/cli/<command>.py to see how each command is wired.

Quick reference card

# bootstrap a new project
harness create

# refresh after code changes
harness update

# gate the worktree
harness lint --gate architecture --format json
harness evaluate --format json

# plan + resume an agent task
harness plan --task "Refactor auth middleware"
harness status
harness resume --task-id <id>

# boot an isolated instance
harness boot --port 8888 --health /healthz

# observability
harness observe --tail
harness screenshot --url http://localhost:8888

# composition
harness create --then lint --then evaluate

For every other detail, open the reference files alongside this skill.