Native, local-first API client.
Terminal CLI and TUI on Probe, with persistent run history.
Quick start · Agent use · 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.8.1 on main (this release); 0.8.0 released (Oct 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.
Coding agents should use the bundled skill and the CLI (Agent use). facet mcp still 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.8.0 · OpenCollection YAML · Ratatui TUI · SQLite run history
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.
The CLI is not cargo install facet. The Cargo package is facet-cli; the binary is facet.
v0.8.0 tag (primary, Rust required):
cargo install --git https://github.com/Hedronite/facet --tag v0.8.0 --locked --bin facet facet-cliFrom main (secondary): cargo install --git https://github.com/Hedronite/facet --locked --bin facet facet-cli, or clone and cargo build --release -p probe-cli -p facet-cli. See docs/install.md.
Release archive: download from GitHub Releases, extract facet, add to PATH.
Verify: facet --version and facet doctor --json.
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 tuiMore 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 |
Same commands as MCP tools over stdio; still shipped. Agents should prefer the skill |
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/.
The default way for an agent to use this tool is the bundled skill in
.agents/skills/facet/: a short SKILL.md
the harness reads to decide when to use it, plus a Nushell body that calls
the CLI with JSON output. The MCP server (facet mcp) is still built and
shipped, and works the same as before.
Why the skill is the default:
- Context. An MCP server adds every tool's name, description and input schema to the model's context, often on every request, whether or not the tools are used. Many harnesses can only turn a whole server on or off. A skill costs a few dozen tokens of description until it is used.
- Determinism. The skill body is fixed code over a versioned JSON contract, so results are the same each time.
- Small models. Local models with short context windows feel the schema cost most.
Use the MCP server when your harness defers or filters MCP tool schemas (loading them only on demand, or letting you enable single tools), or when the client has no shell.
The same files are checked in as ordinary files (not symlinks) at
.claude/skills/facet/, .grok/skills/facet/, and .cursor/skills/facet/.
scripts/sync-skills rewrites those copies from
.agents/skills/. There is no .omp/skills/ or .codex/skills/ tree.
| Key or command | Action |
|---|---|
:open <path> |
Mount a collection without quitting |
:recent |
Open recently recorded collections |
? |
Show the complete keymap and command hints |
| 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.
YAML holds the collection; facet-lattice holds the history.
.facet/lattice.dbbeside 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
.agents/skills/facet/ # canonical agent skill (SKILL.md + Nushell CLI wrapper)
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
0.8.1 on main (this release). 0.8.0 released (Oct 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.
Issues and pull requests welcome. Start with AGENTS.md and docs/FACET.md.
Upstream lineage: Probe (Apache-2.0). Facet-original crates (facet-cli, facet-lattice, facet-tui): MIT. See LICENSE and NOTICE.