CLI reference
The fcheap binary manages a local vault of file and directory snapshots. It prints human-readable output by default and stable JSON where --json is supported.
Usage
fcheap [global flags] <command> [arguments] [flags]Run fcheap <command> --help for the flags accepted by the installed version. Run fcheap agent for the embedded agent operating guide.
Commands by job
Save and inspect
| Command | Purpose |
|---|---|
save | Snapshot a file or directory with provenance, hashes, and secret scanning |
artifact-ref | Emit versioned metadata that points to an existing local stash |
publish | Publish one bounded local file to the private artifact service |
pull | Download one private cloud artifact and verify its recorded SHA-256 |
list | Browse and filter stash summaries |
info | Read one complete stash manifest |
restore | Materialize a stash and verify its hashes |
drop | Permanently delete one stash with explicit confirmation |
Search and compare
| Command | Purpose |
|---|---|
analyze | Index one stash for per-file search |
search | Search indexed stashes with keyword, semantic, or hybrid retrieval |
diff | Compare a saved tree with a corresponding current directory |
connect | Use optional vecgrep to rank source code related to saved evidence |
Storage lifecycle
| Command | Purpose |
|---|---|
compress | Archive a stash with zstd, gzip, or uncompressed tar |
ttl | Set, update, or clear expiry metadata |
sweep | Preview or apply removal of expired stashes |
cleanup | Score or categorize cleanup candidates |
vacuum | Remove orphaned derived entries and compact SQLite |
ecosystem-status | Summarize storage and cleanup estimates by producing tool |
Configuration and interfaces
| Command | Purpose |
|---|---|
config | Inspect and update configuration |
doctor | Check paths, indexes, and optional dependencies |
studio | Open the interactive terminal interface |
auth | Pair, inspect, refresh, or remove the private console device session |
mcp | Start the stdio MCP server |
docs | Read embedded documentation or manage the docs site from a checkout |
agent | Print the version-matched agent operating guide; add --json for its structured form |
completion | Generate shell completion scripts |
version | Print version, commit, and build date |
Global flags
Global flags can appear before or after the command:
| Flag | Default | Description |
|---|---|---|
--json | false | Print structured JSON when the command supports it |
--quiet | false | Suppress non-error human output |
--no-color | false | Disable color; file.cheap also honors NO_COLOR |
--stash-dir <path> | configured value | Override the stash vault for this invocation |
--log-level <level> | configured value | Set debug, info, warn, or error logging on stderr |
--help | — | Show command help |
--version | — | Print the root command version string |
A complete first workflow
Saving and indexing are separate unless you request both:
fcheap save ./evidence --tag bug-123 --tool manual --index
fcheap search "checkout stopped" --mode keyword
fcheap info <stash-id>
fcheap restore <stash-id>Copy <stash-id> from the save result. The restore command creates a fresh temporary directory when --to is omitted and reports whether every file matched its manifest hash.
Automation contract
Use --json rather than parsing colored tables. Operational logs and debug traces go to stderr, while command results go to stdout.
Some commands can complete their primary operation and still report a partial failure. For example, a snapshot can be saved even if requested indexing fails, and a payload can be deleted even if derived-index cleanup fails. Inspect status and failed fields as well as the process exit code.
An empty search result or missing vecgrep index can be valid data rather than a runtime error. The relevant command pages document those cases.
Local and remote boundaries
The vault, manifest database, and BM25 index stay on the machine. A configured OpenAI or non-loopback Ollama embedder receives text during semantic/hybrid indexing and search. connect executes the separately installed vecgrep binary.
publish is opt-in and transfers one bounded local file to the private artifact service. It never uploads a local stash automatically and never evicts local source bytes.
pull is also opt-in. It uses the paired device credential to request a short-lived direct transfer, verifies the recorded size and SHA-256, and refuses to overwrite or extract the destination.
artifact-ref lets another tool store a pointer to a local stash. The pointer does not move bytes and resolves only where the referenced vault is available. See Local artifact references for agent tools.