Facet

Native, local-first API client.
Terminal CLI and TUI on Probe, with persistent run history.

Quick start · Install · What you get · How it works · Status · Roadmap · Contributing

Fork of Probe

---

Status: In production use as daily-driver / dogfood local-first API client (CLI/TUI + facet-lattice). 0.6.0 released (Sep 29, 2026); WebSocket/GraphQL/gRPC on the roadmap. Not a toy reference.

Facet is the terminal product: a facet CLI and Ratatui TUI on the same OpenCollection YAML as Probe. facet-lattice is the run-history library underneath — SQLite for runs, bodies, timings, and sessions beside your YAML on disk.

facet mcp serves the same commands as MCP tools over stdio.

Collections stay YAML; Git stays the sync layer. No account or hosted control plane. The facet binary coexists with probe on PATH.

0.6.0 · OpenCollection YAML · Ratatui TUI · SQLite run history

Quick start

Library — facet-lattice on crates.io

cargo add facet-lattice

[dependencies]
facet-lattice = "0.5.9"

use lattice::WorkspaceStore;

The Cargo package is facet-lattice (not lattice — that name on crates.io is unrelated). The Rust import name is lattice.

CLI — the facet binary

The CLI is not cargo install facet. Pick one:

Release archive (fastest): download from GitHub Releases, extract facet, add to PATH.

From git (Rust required):

cargo install --git https://github.com/Hedronite/facet --package facet-cli --bin facet

From a clone (contributors): cargo build --release -p probe-cli -p facet-cli — see docs/install.md.

Verify: facet --version and facet doctor --json.

Run a request and query history

facet request run ./api/users/list-users.yml --environment development --json
facet history --json
facet history --sql "SELECT status, count(*) FROM runs GROUP BY status"
facet blob <sha256>
facet tui

More commands (facet --help for flags):

Command	What it does
facet last [<path>]	Newest matching run; prints its ULID (same filters as history)
facet pin <runId> --as <name>	Name a run in the machine store (pin get, pin list, pin delete)
facet session start|end|list|show	Group runs into a session (use with FACET_SESSION)
facet replay <runId>	Re-send a recorded run from the current YAML
facet diff <idA> <idB>	Compare two recorded runs, hashes first (exit 1 if different)
facet theme check <path> / facet theme list	Validate a facet-tui theme file; list built-in and discovered themes
facet ncl check|export|apply|pack	Check, export, apply, or pack Nickel (.ncl) configs, evaluated in-process
facet mcp	Serve the same commands as MCP tools over stdio

Full install guide (wrong-name traps, PATH, versions): docs/install.md.

Example collection for calling the TypeSafe API from facet (judge-style requests, API key stored with facet env set --secret): docs/jev-native.md and docs/examples/typesafe/.

TUI quick reference

Key or command	Action
:open <path>	Mount a collection without quitting
:recent	Open recently recorded collections
?	Show the complete keymap and command hints

What you get

	Upstream Probe	Facet (this repository)
Core Engine	Rust, filesystem-first	Same core, cherry-pickable
Collections	OpenCollection YAML	Same YAML, 100% compatible
Interface	GPUI Desktop + CLI (upstream)	Ratatui TUI (facet tui) + agent CLI; the in-repo probe binary is CLI-only
History	In-memory session	facet-lattice (SQLite workspace & machine store)
Binaries	probe	facet (coexists with probe)
Output	Human-readable & JSON	Deterministic, versioned JSON for automation

Facet rebuilds the terminal and history layers; Probe owns the core domain and HTTP execution. Boundary: docs/FACET.md.

How it works

YAML holds the collection; facet-lattice holds the history.

• .facet/lattice.db beside your collection stores run history; a machine store holds secrets, sessions, and a cross-workspace index.
• Agent commands (history, last, pin, session, replay, diff, blob, gc) emit deterministic JSON. Large bodies are content-addressed.
• Secrets use the OS keyring or XChaCha20-Poly1305 via FACET_SECRET_KEY.

Repository map

crates/facet/             # facet CLI binary (facet-cli)
crates/lattice/           # facet-lattice library (crates.io)
crates/facet-tui/         # Ratatui interface
crates/cli/               # upstream probe-cli
crates/core/              # upstream probe-core
docs/install.md           # install guide
docs/FACET.md             # Facet contracts

Status

0.6.0 released (Sep 29, 2026). The facet-lattice crate is a separate version axis and does not follow the CLI: facet-lattice 0.5.9 is live on crates.io, with 0.5.8 still up (no yank).

• facet-lattice: SQLite default. Scrubbed crate package published as 0.5.9.
• CLI + TUI: shipped. Deterministic JSON, SQL over history, Ratatui interface.
• Themes: user-defined theme files ship (facet theme check|list, themes/).
• Roadmap: WebSocket, GraphQL, gRPC — IMPLEMENTATION_PLAN.md.

Contributing

Issues and pull requests welcome. Start with AGENTS.md and docs/FACET.md.

License

Upstream lineage: Probe (Apache-2.0). Facet-original crates (facet-cli, facet-lattice, facet-tui): MIT. See LICENSE and NOTICE.