@harnessconfig/cli

Alpha scoped implementation package for the Harness config CLI. The public CLI package is harnessc.

Most users should run:

npx harnessc
npx harnessc validate
npx harnessc explain .agents/skills/review/SKILL.md

This package exists so the public harnessc package can depend on a scoped implementation package while keeping npx harnessc clean.

Commands

harnessc validate
harnessc explain .agents/skills/review/SKILL.md
harnessc init
harnessc activate
harnessc activate --yes
harnessc extension activate --all --yes
harnessc init --resource prompts --target ./runtime/agent
harnessc init --yes --resource prompts --target ./runtime/agent

Website: https://www.harnessconfig.dev/

Specification: https://www.harnessconfig.dev/specifications/v1/

The CLI is local-first, read-only by default for validation and planning, and does not create standard files or mutate projection targets unless the relevant command is explicitly applied with --yes.

Privacy And Telemetry

Harness config does not collect telemetry.

The harnessc CLI does not send analytics, usage events, file paths, repository names, command history, machine identifiers, or error reports.

Activation, validation, and planning run locally against files in your repository. The CLI does not make network requests during normal operation.

Command Behavior

Running harnessc with no command validates the nearest repository config and prints the detected manifest path with suggested next steps. Use harnessc validate --json when a script or editor integration needs the full inspection object.

harnessc init is a dry run by default. With --yes, it writes ./.harness/harness.toml by default, resource folders under ./.harness/resources by default, and a commented repo-root ./.harnessIgnore. Use --config <path> to write a different repo-local manifest and --resources-path <path> to set an explicit [[resources]] entry and create resource folders below that source root. With no --resource flags, init uses the conventional resource folders skills, rules, and plugins. With one or more --resource <kind> flags, init creates only those folders. Targets are explicit; declare them with --target <path> for repo-local outputs, or edit the selected manifest to add a target parent for output under an external folder such as a sibling worktree. [[resources]].path, [[dir]].path, and [[targets]].parent may use gitignore-style wildcard patterns; [[targets]].path remains a static target-local folder that activation may create.

harnessc init without --yes is the read-only initialization/adoption plan. It does not infer targets from existing folder names. Declare targets with --target <path> during init or edit the selected manifest. Use harnessc activate without --yes for the projection preview.

harnessc explain <path> is read-only introspection for a source or output path. It reports matching target outputs, configured source roots, source-use paths, dir actions, ignore decisions, and diagnostics. Use --json for automation; JSON output includes source and target-output ignore traces.

Examples:

harnessc explain .agents/skills/review/SKILL.md
harnessc explain AGENTS.md
harnessc explain .harness/local/resources/skills/review/SKILL.md

harnessc activate is the reference projection command. Without --yes, it prints a dry run for every declared target, including creates, updates, mutable skipped files, requested removals, projected keeps, orphaned managed outputs, and unmanaged entries preserved outside the projection. With --yes, it applies the computed copy projection. Target symlinks that occupy projected paths are conflicts by default; set [activation].targetSymlinks = "replace" or pass --replace-target-symlinks when replacing the link itself is intended.

harnessc extension activate runs registered extensions. Extensions default to explicit activation; use --extension <id> for one extension or --all for all declared supported extensions. This release ships no built-in extension implementations. Dir composition and copy are now part of core activation; declare [[dir]] entries in the selected manifest and let harnessc activate handle them.

Unmanaged target entries are kept by default. Use --remove-unmanaged when a target should be cleaned to match configured sources; use --keep-unmanaged to make the default explicit. Repeating the same activation with unchanged inputs and the same unmanaged cleanup choice should converge to the same plan.

Orphaned managed outputs are kept by default. Use --remove-orphans when stale outputs from a non-active profile or target selection should be removed, and use --keep-orphans to make the default explicit. --remove-orphans removes only orphaned outputs whose current bytes still match the non-active source projection; edited orphaned outputs and genuinely unmanaged entries stay in place.

Managed files are compared directly with the current projection and reported as update when target bytes differ. Applying an update overwrites the target with the current source bytes. Mutable files declared in .harnessMutable are created once from source and then left untouched as runtime-owned target state unless --force-mutable is supplied.

.harnessIgnore files can be repo-root, source-local, profile-local, target-derived override-local, or target-output-local. Precedence follows logical directory depth with last matching rule wins. Target-output files, such as .agents/skills/review/.harnessIgnore, match final output paths for that subtree, remain the final boundary, and are preserved even when activation is run with --remove-unmanaged.

.harnessProfile files select optional profile overlays. A matching .harnessProfileRoot under .harness, a configured resources source, or a configured dir source merges into resources and dir outputs by logical source path, so local or team-specific kits can add files or replace composable parts without turning target folders into source roots. Optional .harnessProfileIsolation files inside profile roots can make the selected profile exclusive for chosen resource or dir paths while leaving unrelated source paths active.

Human terminal output uses ANSI color when the output stream supports it and keeps --json output unstyled for automation. Set NO_COLOR to disable color or FORCE_COLOR=1 to force it.