CLI Reference¶
Five commands: check, query, build, spec, and formats. check, query, and build take a PATH argument that defaults to the current directory, so you can run 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. Once it has found a README it also prints warnings, pass or fail: files that are neither in a durable format nor UTF-8 text, SQLite databases with unsaved changes in a -wal or -journal sidecar, and directories too deep to inspect. Warnings never change the exit code. Add --verbose (-V; lowercase -v is --version) to see the README path, description, durable formats, which readers can open the source's own files, any extra frontmatter, and the files behind each warning.
Exit codes: 0 compliant, 1 not compliant, 2 the path does not exist or is not a directory.
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, and warnings when there are any) for downstream tooling. Each warning has a kind (unrecognized-format, sidecar-at-risk, or not-inspected), a message, and the paths it concerns, relative to the source.
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. Images, audio, and video a browser can play get an inline preview; files check would warn about are listed and marked. Because everything is self-contained, it opens straight from file:// with no server.
If the target site/ is not empty and was not generated by longecho (another tool's stamp, or no README at all), build refuses to overwrite it. Pass --force (or -f) to override that protection. Use --output to write elsewhere (outside the archive, data links become absolute file:// URIs; the archive directory itself, or one containing it, is refused), 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, the durability criteria, and the durable formats. The format list and the durability criteria in it are rendered from the same code that enforces compliance.
longecho spec
formats¶
List the recognized durable formats, grouped by category. Each entry shows which readers can open it (a standard tool, a web browser, a text editor) and the reason it qualifies under the Library of Congress sustainability factors. The list is rendered from the one table in code that check uses, so it always reflects what check accepts. --json prints the same list as data (extensions, media type and its common aliases, category, readers, rationale).
longecho formats
longecho formats --json | jq '.[] | select(.readers | index("web browser")) | .extensions'