# @fabric-harness/cli

> Command-line interface for [Fabric Harness](https://github.com/Fabric-Pro/fabric-harness) — run, build, deploy, inspect, and operate agents from one binary.

## Install

```sh
npm install -g @fabric-harness/cli
# or
pnpm add -g @fabric-harness/cli
```

Provides two commands (aliases of each other):

- `fabric-harness`
- `fh`

## Quick start

```sh
fh init                                             # scaffold a new .fabricharness/ workspace
npm install                                         # install the deps the scaffolder declared
fh agents                                          # list workspace agents
fh describe hello                                   # show agent metadata + schema
fh run hello --payload '{"name":"Ada"}'             # one-shot run
fh dev                                              # watch mode — POST /agents/:name
fh dev --console                                    # watch mode with the Fiber terminal UI
fh fiber                                            # connect Fiber to an existing local server
fh build --target node                              # build deployable artifact
fh sessions                                         # list persisted sessions
fh inspect <session-id>                             # session history snapshot
fh metrics <session-id>                             # tokens, tools, mounts, per-source bytes
```

## What's in the box

- **`fh init [--dir <path>] [--model <provider/model>] [--force]`** — scaffold `.fabricharness/` (sample agent, role, skill, config) plus `package.json`, `tsconfig.json`, `AGENTS.md`. Idempotent.
- **`fh run / dev`** — local execution against any workspace agent.
- **`fh fiber`** — optional keyboard-first terminal UI for jobs, persistent agents,
  tool activity, and approvals. Use `--plain` for the line-oriented fallback.
- **`fh build`** — emit deployable artifacts for: `node`, `docker`, `temporal-worker`, `cloudflare`, `foundry-hosted-agent`, `databricks-app`, **`aks`** (Dockerfile + `k8s/` Deployment/Service manifests with health probes), **`aca`** (Dockerfile + `azure.yaml` + `infra/main.bicep` for `azd up`). Agent definitions and source-only workspace contracts are bundled so the output directory can be staged without the producer repository.
- **`fh agents / describe`** — agent discovery and schema introspection.
- **`fh sessions / inspect / logs / metrics`** — session history operations. `fh metrics` reports tokens, tools, shells, **mounts** (count / files / bytes), and top tools / sources.
- **`fh replay <id> [--from <step-id>] [--limit <n>]`** — read-only active-path filter from a specific entry id.
- **`fh approvals / approve / reject`** — capability-policy approval handling.
- **`fh checkpoints / artifacts / artifact get`** — durable state inspection.
- **`fh tasks / task / cancel-task`** — task tree management.
- **`fh doctor`** — environment, model provider, Databricks target, and Buzz bridge validation.
  Databricks App reports separate offline contract support, exact public live certification,
  preview reachability, and claims that remain unestablished; `--live` adds bounded read-only
  workspace probes.
  Buzz `--live` performs signed, read-only relay membership and Lakebase/PostgreSQL health
  certification with redacted operational evidence.
- **`fh buzz reconcile [--dry-run] [--limit <1-1000>]`** — preview or replay one bounded durable
  Buzz dead-letter batch through the ordinary signed ingress path. Output is content-free and a
  record is acknowledged only after successful ingress.
- **`fh temporal-worker`** — start a local Temporal worker with Fabric activities.
- **`fh add`** — install connector recipes (sandbox, MCP, data).
- **`fh verify-attestation / verify-provenance`** — supply-chain checks for built artifacts.

Databricks support is loaded only for Databricks-specific commands so the base CLI remains
lightweight and compatible with its documented Node floor. Install `@fabric-harness/databricks`
in the project before using `fh deploy --target databricks-serving`; `fh init --target databricks`
and the managed Databricks recipes declare it automatically.

Run `fh --help` for the full surface.

## Documentation

- [CLI reference](https://harness.fabric.pro/docs/cli)
- [Getting started](https://harness.fabric.pro/docs/getting-started)
- [Headless mode](https://harness.fabric.pro/docs/getting-started/headless-mode) — the 10-line agent path
- [Portable agent packages](https://harness.fabric.pro/docs/deployment/portable-packages)

## License

Apache-2.0