MAR CLI Reference

The basic form of mar commands is:

mar <command> [options] <arguments>

Use mar <command> --help for command-specific options. Archive names should end with .mar, though this is not required.

Common Options

These options apply to all commands:

Option	Description
`-h, --help`	Display help message
`-q, --quiet`	Suppress non-error output
`-v, --verbose`	Enable verbose output (repeat for more detail)
`--stopwatch`	Report command execution time

Commands

Command	Description
`create`	Create an archive from files or directories
`extract`	Extract files from an archive
`list`	List contents of an archive
`get`	Extract specific files to stdout or directory
`cat`	Dump file contents to stdout or as JSON
`diff`	Compare two archives and show differences
`redact`	Overwrite file data with zeros and mark redacted
`index`	Create a sidecar index for an archive
`search`	Search an archive using a sidecar index
`hash`	Compute a fast archive hash
`header`	Display archive header information
`validate`	Validate archive integrity and checksums
`version`	Display version information

`create`

Create a new MAR archive from files or directories.

mar create [options] <archive> [files...]

Options

Option	Description
`-c, --compression <algo>`	Compression algorithm: `none`, `lz4`, `zstd` (default), `gzip`, `bzip2`
`--compression-level <n>`	Codec level (`-1` = default; valid ranges depend on `--compression`)
`--checksum <type>`	Per-block checksum: `xxhash3` (default), `xxhash32`, `blake3`, `crc32c`, `none`
`-m, --multiblock`	Use multiblock mode (default)
`--single-file`	Use single-file-per-block mode
`--block-size <bytes>`	Target block size (default: 1 MB)
`--name-format <fmt>`	Name table format: `auto` (default), `raw`, `front-coded`, `trie`
`-f, --force`	Overwrite existing archive
`-T, --files-from <file>`	Read file list from file (`-` for stdin)
`-j, --threads <num>`	Parallel threads (default: CPU cores)
`--no-checksum`	Skip per-block checksums (same as `--checksum none`)
`--deterministic`	Produce reproducible output
`--no-posix`	Skip storing POSIX metadata (UID, GID, mode, mtime)
`--hashes`	Compute and store BLAKE3 hashes for every file
`--dedup`	Deduplicate identical files by content hash (requires `--hashes`)
`--no-metadata`	Disable optional metadata (POSIX and file hashes)

Examples

mar create archive.mar file1.txt file2.txt
mar create -c lz4 archive.mar ./mydir/
mar create --checksum blake3 --hashes --dedup archive.mar ./data/
mar create --deterministic archive.mar ./mydir/
find . -name "*.txt" | mar create -T - archive.mar

`extract`

Extract files from an archive.

mar extract [options] <archive> [files...]

Options

Option	Description
`-o, --output <dir>`	Output directory (default: current directory)
`-c, --stdout`	Write all files to stdout (binary)
`--strip-components <N>`	Strip N leading path components
`-T, --files-from <file>`	Extract only files listed in file (`-` for stdin)
`-j, --threads <num>`	Parallel threads (default: CPU cores)
`-v, --verbose`	Show extracted files

Examples

mar extract archive.mar
mar extract -o /tmp/output archive.mar
mar extract -c archive.mar | tar xf -
mar extract --strip-components 1 archive.mar

`list`

List the contents of an archive.

mar list [options] <archive>

Options

Option	Description
`-v, --verbose`	Include archive header and summary
`--table`	Display as aligned table (mode, owner, size, checksum)
`--header`	Show column headers (with `--table`)
`--format <fmt>`	Output format: `json`
`--no-meta`	Suppress headers and summary
`--no-checksum`	Omit checksums in table output
`-j, --threads <num>`	Parallel threads (default: CPU cores)

Examples

mar list archive.mar
mar list --table --header archive.mar
mar list --format json archive.mar

`get`

Extract specific files from an archive without full extraction.

mar get [options] <archive> <file1> [file2...]

Options

Option	Description
`-o, --output <dir>`	Extract to directory
`-c, --stdout`	Write to stdout
`--strip-components <N>`	Strip N leading path components
`--json`	Output as JSON with base64 content
`-j, --threads <num>`	Parallel threads (default: CPU cores)
`-v, --verbose`	Show progress

Examples

mar get archive.mar path/to/file.txt
mar get -c archive.mar config.json
mar get -o /tmp archive.mar file1.txt file2.txt

`cat`

Dump file contents to stdout or as JSON.

mar cat [options] <archive> [files...]

Options

Option	Description
`-o, --output <file>`	Write to file instead of stdout
`--all`	Output all regular files in the archive
`--fmt json`	Output as JSON array with `filename` and `contents` fields
`-j, --threads <num>`	Parallel threads (default: CPU cores)
`-v, --verbose`	Show progress

Examples

mar cat archive.mar file.txt
mar cat --all archive.mar
mar cat archive.mar --fmt json | jq '.'
mar cat -o output.bin archive.mar file1 file2

`diff`

Compare two archives and show differences.

mar diff [options] <archive1> <archive2>

Options

Option	Description
`--delta, -d`	Show git-diff style file-level changes
`-v, --verbose`	Show detailed statistics

Examples

mar diff old.mar new.mar
mar diff --delta old.mar new.mar
mar diff -v old.mar new.mar

`redact`

Overwrite the stored data for one or more files with zeros and mark entries as REDACTED.

By default, writes a new archive (original is unchanged). Use -I to modify in-place. If the archive contains deduplicated files (shared spans), redacting one file will also mark any other entries sharing the same blocks as redacted.

mar redact [options] <archive> <file1> [file2...]

Options

Option	Description
`-o, --output <path>`	Output archive path (required unless `-I`)
`-I`	Redact in-place (modifies `<archive>`)
`-T, --files-from <file>`	Read file list from file (`-` for stdin), one per line
`-f, --force`	Overwrite output archive if it exists
`-v, --verbose`	Show redaction summary

Examples

mar redact -o out.mar in.mar secrets.txt keys.pem
printf "a\nb\n" | mar redact -I -T - in.mar

`index`

Create a sidecar index (.mai file) for an archive. See Indexing and Search for detailed usage of each index type.

mar index [options] -i <archive> --type <type>

Options

Option	Description
`-i, --input <archive>`	Path to the `.mar` archive
`--type <type>`	Index type: `minhash`, `vector`, `bm25`, `genomic`, `email`, `timeseries`
`--aux <file>`	Auxiliary input file (repeatable)
`--with <key=value>`	Type-specific parameter (repeatable)
`-o, --output <file>`	Custom output path (default: `<archive>.<type>.mai`)
`--align <log2>`	Section alignment as 2^n bytes (default: 0)

Use mar index --type <type> --help for type-specific options.

Examples

mar index -i data.mar --type minhash --with bit_width=16
mar index -i data.mar --type vector --with url=http://localhost:7998
mar index -i data.mar --type bm25
mar index -i data.mar --type genomic
mar index -i mail.mar --type email
mar index -i sensors.mar --type timeseries --with ts_col=timestamp --with ts_format=iso8601

`search`

Search an archive using a sidecar index.

mar search [options] -i <archive> --index <index.mai> [query]

Options

Option	Description
`-i, --input <archive>`	Path to the `.mar` archive
`--index <index.mai>`	Path to the sidecar index file
`--with <key=value>`	Search parameter (repeatable; type-specific)
`--extract`	Genomic: write raw sequence/records to stdout
`--filenames-only`	Shorthand for `--with format=filenames`

Universal `--with` Parameters

Parameter	Description
`topk=N`	Maximum results to return (default: 10)
`format=text\|json\|filenames`	Output format (default: text)
`threads=N`	Worker threads

Exit Codes

Code	Meaning
0	Results found
1	No results
2	Usage error
3	Runtime error

Examples

# MinHash similarity
mar search -i data.mar --index data.minhash.mai --with file=query.txt

# Vector semantic search
mar search -i docs.mar --index docs.vector.mai "Hamilton case" \
  --with url=http://localhost:7998 --with topk=5 --with format=json

# Genomic region extraction
mar search -i ref.mar --index ref.genomic.mai chr1:1000000-2000000 --extract

`hash`

Compute a deterministic, fast hash of the archive bytes.

mar hash [options] <archive>

Options

Option	Description
`-a, --algo <algo>`	Hash algorithm: `xxhash64` (default), `blake3`, `md5`

Examples

mar hash archive.mar
mar hash -a blake3 archive.mar

`header`

Display archive header information.

mar header [options] <archive>

Options

Option	Description
`-v, --verbose`	Show detailed header information

Examples

mar header archive.mar
mar header -v archive.mar

`validate`

Validate archive integrity and verify checksums.

mar validate [options] <archive>

Options

Option	Description
`-j, --threads <num>`	Parallel threads (default: CPU cores)
`-v, --verbose`	Show detailed validation results
`-q, --quiet`	Suppress output (exit code only)

Examples

mar validate archive.mar
mar validate -v archive.mar

`version`

Display version and build capability information.

mar version [options]

Options

Option	Description
`-n, --mar-version`	Print MAR format version only
`-c, --capabilities`	Print supported algorithms and features for this build

Examples

mar version
mar version -n
mar version -c

Exit Codes

Code	Meaning
0	Success
1	General error
2	Usage error
65	Integrity error (checksum mismatch)
69	Unavailable feature

MAR CLI Reference

Common Options

Commands

create

Options

Examples

extract

Options

Examples

list

Options

Examples

get

Options

Examples

cat

Options

Examples

diff

Options

Examples

redact

Options

Examples

index

Options

Examples

search

Options

Universal --with Parameters

Exit Codes

Examples

hash

Options

Examples

header

Options

Examples

validate

Options

Examples

version

Options

Examples

Exit Codes

`create`

`extract`

`list`

`get`

`cat`

`diff`

`redact`

`index`

`search`

Universal `--with` Parameters

`hash`

`header`

`validate`

`version`