CLI: pack & unpack

The uap command turns harness layouts into canonical bundles and back. One binary, five commands.

Install

npm install -g uap-protocol    # puts `uap` on your PATH

uap --help

Or from source: git clone github.com/BrainbaseHQ/uap && npm install && npm link --workspace uap-protocol.

uap pack

Capture a harness layout as a UAP bundle.

uap pack --from claude-code                  # pack the current directory
uap pack --from codex ./service -o ./bundle  # read ./service, write to ./bundle

Option	Default	Meaning
`--from <harness>`	required	Harness to read.
`[dir]`	`.`	Project directory to read.
`-o, --out <path>`	`<dir>`	Bundle output directory.
`--force`	off	Overwrite an existing `agent.uap.yaml`.
`--json` / `-q`	off	Machine report / quiet.

Pack never guesses ownership of your files, redacts anything secret-shaped into ${PLACEHOLDERS}, and refuses to overwrite an existing bundle without --force.

uap unpack

Render a bundle into a harness's on-disk layout.

uap unpack --to codex                         # install ./agent.uap.yaml as codex
uap unpack --to cursor ./proj -b ./bundle     # bundle and project in different dirs
uap unpack --to devin --on-unsupported error  # fail if anything can't be represented

Option	Default	Meaning
`--to <harness>`	required	Harness to install into.
`[dir]`	`.`	Project directory to write into.
`-b, --bundle <path>`	`<dir>`	Bundle directory or `*.uap.yaml`.
`--on-unsupported`	`warn`	`skip` \| `warn` \| `error`.
`--no-validate`	validates	Skip the pre-install safety gate.

Unpack validates before writing anything — schema, path containment, and a secret-leak scan. A bundle with errors is refused. Installs are idempotent: re-running an unchanged unpack reports unchanged and touches nothing, and your hand-written content outside UAP's managed regions is never modified.

uap convert

The hub-and-spoke conversion — pack then unpack through a temporary canonical bundle:

uap convert --from claude-code --to codex

uap validate & uap adapters

uap validate ./bundle        # schema, references, safety, hygiene
uap validate --strict        # warnings become errors
uap adapters                 # capability tables for every harness

Fidelity reports

Every command reports what happened to each component:

  ✅ instructions/core
  ◐  instructions/frontend-rules  (activation "auto" folded into CLAUDE.md)
  —  hooks/pre_tool_use[0]        (hooks not supported by this adapter yet)

  unpack was LOSSY — see entries above.

--json emits the structured report for CI. Exit code 0 means success; 1 means an error, a failed component, a validation failure, or a refused overwrite. See the support matrix for what each harness can represent.