Getting started

This guide walks through install, a first catalog apply, and the follow-up scan/compose/publish loop. For every command and flag, see the command reference. For deeper workflows, browse the scenario guides.

Requirements

• Node.js 20 or later
• Bun 1.3+ (optional; required only when contributing from source)

Install

Recommended: npx (no global install)

npx harnesstap@latest init

npm global

npm install -g harnesstap
ht init

Bun (alternative)

bun install -g harnesstap
ht init

Or run without a global install:

bunx harnesstap@latest init

ht is shorthand for harnesstap throughout these docs.

Quick start

Apply a public catalog baseline in a few minutes.

1. Initialize local state (creates ~/.harnesstap and scans supported home harness folders).

   ht init --main codex --aliases claude-code,cursor

2. Apply a catalog layer by bare name (fetches from the public HarnessTap Cloud catalog when needed).

   ht layer list --search foundation --remote-only
   ht layer apply engineering-foundation

3. Inspect project state and next steps.

   ht status .
   ht help

When a repository has a git origin, ht layer apply stores a snapshot before writing files. Restore it later with ht revert.

Starter layers such as engineering-foundation live in the public cloud catalog, not inside the npm package. To opt out of anonymous public catalog lookups, set catalog.publicCatalog: false in ~/.harnesstap/config.jsonc or export HARNESSTAP_PUBLIC_CATALOG=0.

Follow-up: scan, compose, and publish

After the baseline fits, build and share your own layers.

1. Scan the current repository and review imports.

   ht scan .
   ht resource list

2. Create a reusable layer and add resources.

   ht layer create my-setup --description "Shared project assistant setup"
   ht layer edit my-setup --add research-helper --type skill

3. Apply, mirror alias harnesses, or publish to the cloud catalog.

   ht layer apply my-setup --project . --harness claude-code,cursor
   ht mirror .
   ht auth login
   ht layer catalog register acme/default
   ht layer publish my-setup

4. Manage harness preferences after init.

   ht harness status --format json
   ht harness set --main claude-code --aliases cursor,codex

Where data lives

Operational state lives in ~/.harnesstap/harnesstap.db (resources, layers, environments, tracked projects, snapshots). Optional settings live in ~/.harnesstap/config.jsonc. Override the base directory with HARNESSTAP_HOME.

init seeds a default profile layer and writes active-profile.json, but does not run global apply automatically. Run ht profile use default to materialize home harness files. See Profiles.

Next steps

• Command reference — grouped CLI surface and flags
• Concepts overview — architecture and data model
• HarnessTap Cloud — authenticate and work with shared layers
• Scenario guides — numbered playbooks (preview/apply, drift, mirror, migration, …)