casq 0.11.0

A minimal content-addressed file store using BLAKE3. (CLI)
casq-0.11.0 is not a library.

casq — CLI for the casq content-addressed store

Overview

casq is the command-line interface for a small, local-only content-addressed file store. It stores files and directories as immutable objects addressed by their cryptographic hash (BLAKE3 by default), can reconstruct trees, list contents, and garbage-collect unreferenced data.

Status

Alpha — useful for local single-user workflows. JSON output and strict stdout/stderr separation are supported for scripting.

Key features

  • Content-addressed storage using BLAKE3-256.
  • Three object types: blob (file), tree (directory), and chunk-list (for large files in casq_core).
  • Store layout: $STORE_ROOT/{config,objects,refs,journal}.
  • Refs as named text files under refs/; GC computes reachability from refs.
  • --json support for machine-readable output; informational messages/errors go to stderr in JSON mode.

Quick install & development

This repository uses mise for task automation. Common tasks:

  • list tasks: mise tasks
  • fetch deps: mise run deps
  • build: mise run build
  • test: mise run test

You can also use cargo directly for local development:

  • Build the CLI: cargo build -p casq
  • Run the CLI: cargo run -p casq --

Usage

General form: casq [OPTIONS]

Commands

  • initialize Initialize a new store
  • put Put files or directories into the store
  • materialize Materialize an object to the filesystem
  • get Output blob content to stdout
  • list List tree children
  • metadata Show object metadata
  • collect-garbage Garbage collect unreferenced objects
  • find-orphans Find orphaned objects (unreferenced trees and blobs)
  • references Manage named references (add/list/rm)
  • help Show help for commands

Global options

  • -R, --root Store root directory (defaults to CASQ_ROOT env var or ./casq-store)
  • --json Output results as JSON
  • -h, --help Print help
  • -V, --version Print version

Examples

  • Initialize a new store: casq initialize --root ./casq-store

  • Add a directory and print the root hash: casq put path/to/dir

  • Materialize a tree to the filesystem: casq materialize ./restore-dir

  • Stream a blob to stdout: casq get > file.bin

  • List a tree's contents: casq list

Notes & conventions

  • Object files are named by the hex-encoded hash and stored under objects///.
  • Tree entries are canonicalized (sorted by name) to ensure stable tree hashes.
  • When using --json: only JSON is written to stdout; informational messages and errors go to stderr.

Contributing

See the repository README for contribution guidelines. Before making changes that affect structure, API, or behavior, update relevant documentation files (CLAUDE.md and top-level READMEs) as appropriate.

License

Apache-2.0