CLIScenarios
User scenarios
Workflow guides for the current HarnessTap CLI, grouped by usage frequency.
This document reflects the current shipped CLI. Each scenario links to a detail page with typical commands.
Orientation
- Machine-wide setup:
init,profile use,harness set(Scenarios 1, 2, 36) - Repo adoption:
scan,layer apply,mirror(Scenarios 4, 7, 27) - Layer curation:
layer create,layer edit,layer doctor,add(Scenarios 5, 23, 35) - Plugin pins:
resource sync,layer show,layer apply --strict-plugin-versions(Scenarios 8, 16) - Repo profiles:
config show,ht use(Scenario 40) - Sharing:
migrate export/import,layer pull/layer publish(Scenarios 10, 28)
See the VHS demo pack for rendered walkthroughs of the covered workflows.
Usage frequency
Frequency describes how often a typical active user reaches for a scenario after HarnessTap is set up — not how important it is the first time.
| Frequency | Meaning |
|---|---|
| Common | Regular per-repo work: onboarding, adoption, repo-specific prefs, applying layers |
| Occasional | Setup, customization, sharing, maintenance, automation, CI integration |
| Rare | Edge cases, team-only constraints, debugging, or recovery after a mistake |
| Scenario | Title | Frequency | Status |
|---|---|---|---|
| 7 | Preview and apply a layer | Common | Shipped |
| 11 | Start from a catalog baseline | Common | Shipped |
| 4 | Scan and import an existing repo | Common | Shipped |
| 35 | Add a remote skill package | Common | Shipped |
| 38 | Create a layer from a skill package | Common | Shipped |
| 31 | Import dual-mode plugin repo | Common | Shipped |
| 3 | Override harness preferences for one repository | Common | Shipped |
| 15 | Apply to a subset of target platforms | Common | Shipped |
| 25 | Stack multiple layers | Common | Shipped |
| 26 | Turn a project's current state into a layer | Common | Shipped |
| 27 | True cross-harness mirror | Common | Shipped |
| 36 | Switch global profile presets | Common | Shipped |
| 40 | Switch repo profiles from .harnesstap/config.toml | Common | Shipped |
| 1 | Bootstrap HarnessTap on a machine | Occasional | Shipped |
| 2 | Choose a default main harness and aliases | Occasional | Shipped |
| 5 | Build a reusable layer from imported resources | Occasional | Shipped |
| 8 | Audit plugin resources and layer pins | Occasional | Shipped |
| 10 | Export or import a layer bundle | Occasional | Shipped |
| 12 | Drive HarnessTap from scripts or agents | Occasional | Shipped |
| 13 | Choose a materialization strategy (symlink vs copy) | Occasional | Shipped |
| 16 | Enforce layer and plugin state in CI | Occasional | Shipped |
| 19 | Sync plugin resources from install trees | Occasional | Shipped |
| 20 | Inspect supported platforms before targeting | Occasional | Shipped |
| 21 | Detect drift between project and last applied layer | Occasional | Shipped |
| 22 | Diff two layers | Occasional | Shipped |
| 23 | Doctor-check a layer without writing | Occasional | Shipped |
| 24 | Apply a layer directly from a URL | Occasional | Shipped |
| 37 | Publish a profile layer to the catalog | Occasional | Shipped |
| 32 | Apply to instruction-tier harnesses | Occasional | Shipped |
| 33 | Mirror with plugin-source fallback | Occasional | Shipped |
| 34 | Understand portability limits | Occasional | Shipped |
| 39 | Switch MCP tokens via environments; OAuth limits | Occasional | Documented |
| 6 | Add plugin constraints to a layer | Rare | Shipped |
| 9 | Review history and recover from a bad apply | Rare | Shipped |
| 14 | Curate and clean up the local resource DB | Rare | Shipped |
| 17 | Migrate HarnessTap state to a new machine | Rare | Shipped (manual) |
| 18 | Debug committed vs effective Claude plugin settings | Rare | Shipped |
| 28 | Share workspace offline with migrate export/import | Occasional | Shipped |
Status legend
- Shipped — the commands shown in the scenario exist in the current CLI.
- Documented — workflow is documented with known product limits (see the scenario detail page).
- Shipped (manual) — achievable today with current commands but as a multi-step workflow (see Scenario 17 vs 28).
Common
Use these when starting or adopting a repository, applying a layer, or when one repo needs different harness defaults than your machine-wide setup.
| Scenario | Summary |
|---|---|
| 7 | Preview and apply a layer to one or more target harnesses |
| 11 | Start from a catalog baseline instead of building from scratch |
| 4 | Scan an existing repository and import its current harness setup |
| 35 | Add a remote skill package |
| 38 | Create a layer from a skill package |
| 31 | Import a repo with both harness files and plugin-source layout |
| 3 | Override harness preferences for one repository |
| 15 | Apply a layer to a subset of target platforms |
| 25 | Stack multiple layers in one apply |
| 26 | Turn a project's current state into a layer |
| 27 | True cross-harness mirror |
| 36 | Switch global profile presets on the machine |
| 40 | Switch repo profiles from .harnesstap/config.toml |
Occasional
Reach for these during initial setup, when curating layers, when sharing baselines, or when integrating HarnessTap into tooling.
| Scenario | Summary |
|---|---|
| 1 | Bootstrap HarnessTap on a machine and discover existing defaults |
| 2 | Choose a default main harness and alias harnesses |
| 5 | Build a reusable layer from imported resources |
| 8 | Audit plugin resources and layer pins |
| 10 | Export or import a layer as a portable bundle |
| 12 | Drive HarnessTap from scripts or other agents |
| 13 | Choose a materialization strategy (symlink vs copy) |
| 16 | Enforce layer and plugin state in CI |
| 19 | Sync plugin resources from install trees |
| 20 | Inspect supported platforms before targeting |
| 21 | Detect drift between project files and the last applied layer |
| 22 | Diff two layers (or a layer vs an imported bundle) |
| 23 | Doctor-check a layer without writing to disk |
| 24 | Apply a layer directly from a URL |
| 28 | Share a full workspace offline with migrate export/import |
| 37 | Publish and install profile-tagged catalog layers |
| 32 | Apply layers to instruction-tier harnesses (windsurf, cline, copilot, …) |
| 33 | Mirror alias harnesses when main harness tree is empty |
| 34 | Review what transfers across harnesses and what does not |
| 39 | Switch MCP tokens via environments; OAuth host limits (Documented) |
Rare
These matter when requirements are strict, when something went wrong, or when maintaining the local DB after a lot of activity.
Connect HarnessTap CLI to HarnessTap Cloud
Authenticate with your cloud account, switch organizations, search and install shared layer bundles, and publish your own layers to your team's...
Scenario 1: Bootstrap HarnessTap on a machine and discover existing defaults
Use this when setting up HarnessTap for the first time on a laptop, dev box, or CI-like agent environment.