v0.6.0 · MIT · Rust

Browse compressed files. Read what you need.

Inspect, read, search, create and convert compressed files. Use the command line, JSON output or a local AI agent.

12 archive formats · stable JSON output · tested on macOS + Linux

~/datasets — zsh

$ arcthis inspect dataset.zip archive: dataset.zip format: zip compression: mixed entries: 7 compressed size: 201315 uncompressed size: 200124 random access: true $ arcthis tree dataset.zip dataset.zip └── dataset ├── README.md ├── docs │ └── notes.md └── train ├── data.csv └── labels.csv $ arcthis read dataset.zip dataset/train/labels.csv id,label 1,cat 2,dog 3,bird

01 — Quickstart

Install and inspect in one command.

v0.6.0 is available through Cargo, Homebrew, npm and pnpm, with MCP included by default. See Download for every install option and prebuilt archives.

install — zsh

$ brew install mkynyd/tap/arcthis

02 — Signature moves

One command style. Every format. Nothing extracted unless you ask.

Use arcthis <command> <archive> [entry] to read and manage ZIP, 7z, RAR, TAR and single-file compression formats.

move / 01

Find matching paths

find matches paths in the file list using wildcards. Sequential formats scan to build that list; queries do not extract files.

find

$ arcthis find dataset.zip --glob '**/*.csv' dataset/train/labels.csv dataset/train/data.csv

move / 02

Search contents in place

grep searches text inside the archive with limits on file size, line length, matches and total results. Binary files are skipped by default.

grep

$ arcthis grep dataset.zip TODO --glob '**/*.md' dataset/docs/notes.md:1:TODO: fill in preprocessing notes dataset/README.md:3:Sample training bundle. TODO: document the schema.

move / 03

Verify without extracting

hash computes a file's SHA-256 or SHA-512 checksum; verify reads the archive start to finish once, checking its structure and every readable file.

hash · verify

$ arcthis hash dataset.zip dataset/train/data.csv 3307d48518fd5bc59980caee9f4833a1aef4a3ae7f16ef4102a132b719d947c2 dataset/train/data.csv $ arcthis verify dataset.zip verified 7 entries (200124 bytes)

move / 04

Rehearse before you write

pack, extract and convert all accept --dry-run to preview the full plan before anything is written. Real writes go to a temporary location first and are saved as final only after verification passes.

pack --dry-run

$ arcthis pack ./dataset --output dataset.tar.zst --dry-run dry-run pack plan source: ~/demo/dataset destination: dataset.tar.zst format: tar_zstd entries: 7 estimated bytes: 200124 collision: false will skip: false delete source after success: false

move / 05

Archives inside archives

Repeat --within to step into archives nested inside archives — up to 8 levels deep, entirely in memory, with no temporary files left on disk.

tree --within

$ arcthis tree backup.zip --within project.tar.gz backup.zip::project.tar.gz └── dataset ├── README.md ├── docs │ └── notes.md └── train ├── data.csv └── labels.csv

move / 06

Structured by default, for agents

Add --json to any query command for versioned JSON: fields stay stable, errors carry fixed codes on stderr, and exit codes are predictable.

stat --json

$ arcthis stat dataset.zip dataset/train/labels.csv --json {"schema_version":"2","archive":{"path":"/data/dataset.zip","path_lossy":false,"index_used":false,"format":"zip"},"entry":{"archive_index":5,"path":"dataset/train/labels.csv","path_encoding":"utf8","path_raw_hex":"646174617365742f747261696e2f6c6162656c732e637376","kind":"file","size":28,"compressed_size":28,"modified_time":null,"modified_time_local":"2026-08-30T01:05:30","encrypted":false,"executable":false,"symlink_target":null,"crc32":"9e6ad3e5","mime_guess":"text/csv"}}

03 — Formats

Twelve formats, one way to work.

Arcthis detects formats by content, not by file extension — a renamed file can't fool it. Each format's quirks are handled under the hood; every command behaves the same and tells you honestly what a format can do.

Format	Access / extract	Create	How it's read
zip	Stored/Deflate, including ZipCrypto/AES decryption	Deflate, unencrypted	Jump straight to any file
7z	Yes, including AES decryption	LZMA2, unencrypted	Depends on compression layout
rar / rar5	Yes (via libarchive)	read-only	Read start to finish
tar	Yes	yes	Read start to finish
tar.gz / tgz	Yes	yes	Decompressed start to finish
tar.bz2 / tbz2	Yes	yes	Decompressed start to finish
tar.xz / txz	Yes	yes	Decompressed start to finish
tar.zst / tzst	Yes	yes	Decompressed start to finish
gzip	Contains one file	yes	Read start to finish
bzip2	Contains one file	yes	Read start to finish
xz	Contains one file	yes	Read start to finish
zstd	Contains one file	yes	Read start to finish

04 — Agent interface

JSON is the contract. Stable fields, versioned schema.

Real structured output. Every successful response is one JSON document with schema_version: "2". Field names and types are a public, versioned interface.
Clean output separation. Results go to stdout; diagnostics, warnings and errors go to stderr. read prints raw file contents and rejects --json.
Predictable failures. Errors come as JSON with fixed codes, each mapped to a deterministic exit code.
Honest costs. inspect reports capabilities like random_access and solid, so an agent can reason about what an operation will cost.

response shape — schema_version "2"

{
  "schema_version": "2",
  "archive": {
    "path": "/data/dataset.zip",
    "path_lossy": false,
    "index_used": false,
    "format": "zip"
  }
}

unsupported_format invalid_archive corrupted_archive entry_not_found unsafe_path resource_limit password_required wrong_password collision verification_failed partial_failure io_error

05 — Safety model

Safe before convenient, by default.

Writes check paths, conflicts and resource limits. Output is saved from a temporary location after success.

paths

One path safety check

Extraction rejects .., absolute paths, Windows drive/UNC prefixes, NUL bytes, and links that could escape the destination.

writes

Temporary first, saved when done

Output is written to a temporary location next to the destination and saved only after every file succeeds. A failure never leaves a half-finished result that looks complete.

collisions

Refuse by default

Choose overwrite, skip or rename for existing destinations. Writes reject overlapping source and destination paths, including conflicts between archives in a batch.

deletion

Source deleted last

--delete-source runs only after the new files are written, verified and saved. Any error, interruption or failed check keeps the source.

06 — MCP

The same commands, straight into your AI agent.

A built-in MCP server. Connect local AI agents over standard input and output. Included in every installation channel.
Nine read-only tools for inspect, list, tree, stat, read, find, grep, hash and verify — available once you explicitly grant a directory with --allow-root.
Six write tools (plan + execute for extract/pack/convert) appear only after you grant an output directory with --allow-output-root.
Plan before execution. Changes to the source or destination invalidate the plan. Clients can only lower the server's file-count and decoded-byte limits.
Configurable call limits. Four active calls and 16 MiB per tool response by default. Grep retains up to 16 MiB of matches.

mcp — zsh

$ cargo build --release --locked --features mcp $ arcthis mcp --allow-root ./archives # read-only tools only $ arcthis mcp --allow-root ./archives --allow-output-root ./outputs # plan/execute mutation tools become visible

Access before extraction.

Install v0.6.0 to read and manage your compressed files.

$ brew install mkynyd/tap/arcthis

Download Read the docs