---
title: "Examples"
description: "What the four gold packs in the reference implementation prove (transit, ledger, echo and the hcp-cli bootstrap), with the commands to run each."
canonical: https://harnesscontextprotocol.io/docs/packs/examples
---

# Examples

> What the four gold packs in the reference implementation prove (transit, ledger, echo and the hcp-cli bootstrap), with the commands to run each.

The reference implementation ships two conformance fixtures to copy, a
composite pack and the bootstrap pack. Copy `transit` for a discovery pack
without a login and `ledger` for anything with a login or an irreversible
write.

| Pack | Class | Adapter | Binding | Proves |
|------|-------|---------|---------|--------|
| [`transit`](#transit) | Public read | `wrap` | `public` | Five closed reads, no login |
| [`ledger`](#ledger) | Gated write | `wrap` | `local` | Installer family, connect, confirm gate |
| [`echo`](#echo) | Demo | `composite` | `public` | In-process exec, sandbox-safe |
| [`hcp-cli`](#hcp-cli) | Bootstrap | `composite` | `local` | The CLI is itself the first pack |

All four live in the SDK repository (`examples/packs/*` and `packs/hcp-cli`).
The wrap packs spawn demo binaries from their own `bin/`, so an installed copy
carries everything it runs.

## transit

```bash
hcpx install ./examples/packs/transit --json
hcpx activate transit --json
hcpx exec transit find --json -- query=Central
hcpx exec transit plan --json -- from=A to=B
hcpx exec transit show --json -- optionId=opt-1
hcpx exec transit status --json
hcpx exec transit follow --json -- runId=run-1
```

```json
{ "ok": true, "pack_id": "transit", "verb_key": "plan", "result": { "ok": true, "verb": "plan", "from": "A", "to": "B", "optionId": "opt-1" } }
```

It has five commands, all `read` and all `personal`, and no `stimuli`.
`follow` is a read an agent may poll rather than Sense. `binding.mode: public`
skips `connect`, though the Principal is still attributed, and `wrap.bin` is a
relative path resolved against the pack directory.

## ledger

```bash
hcpx install ./examples/packs/ledger --json
hcpx activate ledger --json
hcpx exec ledger setup.status --json
hcpx exec ledger setup.apply --json
hcpx exec ledger connect --json -- provider=demo
hcpx exec ledger list --json
hcpx exec ledger transfer --json -- amount=2.80 payee=demo-transit
hcpx exec ledger transfer --json -- amount=2.80 payee=demo-transit confirm=true
```

```json
{ "ok": false, "pack_id": "ledger", "verb_key": "transfer", "code": "confirm_required", "error": "confirm required", … }
```

Its land is `local`, a workspace directory rather than a tenant.
`setup.status` (read) and `setup.apply` (write, `-y`) form the HCP/1.1 installer
family; both are idempotent and open no wizard on the agent path. `connect` is
`write` and needs `pack.connect`, separate from `verb.exec.write`.

`transfer` has `confirm: "always"` in Policy and `--confirm` in `cli[]`, so in
every access mode the runtime refuses it before the bin runs until the ask is
satisfied, by `confirm=true` after the user agreed or by a person's approval.
Its `payment` `preview` makes the approval card lead with the amount and payee
([Access](/docs/concepts/access#what-the-card-shows)). The pack's
`hcp.eval.json` proves this: three reads return what they should, and
`transfer` is refused without confirmation and runs once confirmed
(`hcpx eval ./examples/packs/ledger`). Its Skill's anti-patterns name real
mistakes: env-flag mocks, transfer without confirm and operator bins on this
pack.

## echo

This composite pack has no foreign binary, so it tests a runtime's JSON path
without a sandbox allow-list.

```json title="surface.json"
{
  "id": "echo",
  "kind": "composite",
  "cliBin": "echo-hcp",
  "binding": { "mode": "public" },
  "verbs": {
    "echo.ping": { "description": "Ping the echo pack.", "cli": ["echo-hcp", "ping"] },
    "echo.say":  { "description": "Echo a message back.", "cli": ["echo-hcp", "say", "{{message}}"] }
  }
}
```

```bash
hcpx exec echo echo.say --json -- message=hi
```

Its dotted command names (`echo.ping`) show how a family reads on the wire and
as an in-process tool name (`echo__echo_ping`).

## hcp-cli

The CLI is itself a composite pack with `local` Binding, installed into
`$HCP_HOME` on first run. Its 18 commands are the CLI's own lifecycle
operations, among them `hcp.doctor`, `hcp.availability`, `hcp.list`,
`hcp.search`, `hcp.install`, `hcp.activate`, `hcp.connect`, `hcp.exec`,
`hcp.lint`, `hcp.generate`, `hcp.adopt`, `hcp.skill`, and `hcp.share`, and
they keep the `hcp.` prefix whichever name you run the CLI by.

```bash
hcpx exec hcp-cli hcp.doctor --json
```

Because the bootstrap is a pack, there is always something to exec against,
and the CLI's own Skill is discoverable like any other. Store-mutating commands
(`install`, `activate`) are `write`, and the in-process composite defers them to
the CLI process that owns the store.

## hcp-example

`@harnesscontextprotocol/example` is the gold pack you can install as a package. Its CLI, `hcp-example`, is the protocol CLI's public read lattice (`doctor`, `list`, `lint`, `skill`, `catalog`) with `public` Binding, and the package ships conformance vectors and an eval file beside the three pack files. Like the other HCP packages it is a private preview on GitHub Packages, not on public npm.

```bash
hcpx install npm:@harnesscontextprotocol/example
hcp-example doctor --json
```

Use `transit` as the domain example and `hcp-cli` as the bootstrap; `hcp-example` shows how a pack ships as an npm package (`"hcp": { "pack": "." }` in `package.json`).

## Writing your own

Copy `transit` or `ledger`, change `id`, `cliBin`, `wrap.bin`, the `verbs` map
and `binding.mode`, update the Policy rows and the Skill, and lint.
[Build a pack](/docs/packs) walks through it from `hcpx init`, and
`examples/standalone/transit`, the copy with the demo binary inside the pack, an
MIT licence and a relative `wrap.bin`, is the one to
[extract into its own repository](/docs/packs/share#extract-a-gold-pack-into-its-own-repository).

## Related

- [Pack classes](/docs/packs/best-practices#pack-classes)
- [Testing](/docs/packs/check#testing)
- [Implementations](/docs/community/implementations): packs and runtimes in the wild

## Sitemap

- [Documentation](https://harnesscontextprotocol.io/docs)
- [Packs](https://harnesscontextprotocol.io/packs)
- [Glossary](https://harnesscontextprotocol.io/docs/reference/glossary)
- [llms.txt](https://harnesscontextprotocol.io/llms.txt)
- [llms-full.txt](https://harnesscontextprotocol.io/llms-full.txt)
- [OpenAPI](https://harnesscontextprotocol.io/openapi.json)
- [MCP](https://harnesscontextprotocol.io/mcp)