CLI Reference

Five commands: check, query, build, spec, and formats. Every command takes a PATH argument that defaults to the current directory, so you can run any of them from inside an archive with no path at all. Where a command offers --json, that output is plain text written straight to stdout (not Rich-wrapped), so it pipes cleanly into jq.

For the rules these commands enforce, see Specification.

check

Report whether a directory is longecho-compliant. A directory passes if it has a README.md or README.txt and at least one file in a durable format. longecho checks for the presence of these things, not the correctness of their contents. When a directory fails, check prints a human-readable reason and exits non-zero. Add --verbose to see the README path, description, durable formats, and any extra frontmatter.

longecho check ~/archive

query

Find, search, and filter sources across a tree. With no options it walks the filesystem and lists every longecho-compliant source it finds, indented by depth.

--search "term" does a case-insensitive text search across each source's name, description, README body, and frontmatter values, and keeps only the matches. --depth bounds how deep the walk descends (0 means the root only). --table renders the results as a table instead of the default indented tree. --json emits structured records (path, name, description, durable formats, frontmatter) for downstream tooling.

longecho query ~/

longecho query ~/ --search "bookmarks"

longecho query ~/ --json | jq '.[].name'

build

Generate a single-file browsable site at site/index.html. The page inlines every README and all metadata as JSON, with client-side navigation and search, and links to your data files by relative path. Because everything is self-contained, it opens straight from file:// with no server.

If the target site/ was generated by another tool, build refuses to overwrite it. Pass --force (or -f) to override that protection. Use --output to write elsewhere, or --open to launch the result in a browser.

longecho build ~/archive

spec

Print the specification summary: the five principles (Self-Describing, Durable Formats, Graceful Degradation, Local-First, Trust the Future), the README and contents conventions, and the durable formats. The text is rendered from the same code that enforces compliance, so it cannot drift from the implementation.

longecho spec

formats

List the recognized durable formats, grouped by category. Like spec, the list is rendered from the single source of truth in code, so it always reflects what check actually accepts.

longecho formats