arcthis

A command-line tool for reading and managing compressed files.

arcthis inspects, reads, searches, extracts, creates, converts, and verifies compressed files. It supports twelve formats, JSON output, Unix pipelines, and local AI agents through MCP.

简体中文

Read archive contents

Browse an archive, find a path, and read the selected file:

arcthis inspect dataset.tar.gz --json
arcthis tree dataset.tar.gz --json
arcthis stat dataset.tar.gz train/data.csv --json
arcthis find dataset.tar.gz --glob '**/*.csv' --json
arcthis read dataset.tar.gz train/data.csv | head

read prints one file's contents to stdout, so archive contents work with tools you already have:

arcthis read source.zip src/lib.rs | rg unsafe
arcthis read media.zip video.mp4 | ffprobe -i pipe:0

ZIP can usually read a selected file directly. TAR and TAR.GZ scan in order. inspect --json reports the format's supported operations and access costs.

Project status

Arcthis v0.5.1 includes the CLI and local MCP server. Every installation channel provides the same commands.

Changes in v0.5.1

Writes reject overlapping source and destination paths, including recursive batch conflicts. File trees have depth and path-length limits. MCP limits concurrent calls, response size, and write operations; grep limits the total matching text retained across files. See CHANGELOG.md for details.

Current commands:

• list, tree, stat, inspect, and read (which reads a file directly)
• glob-based find, capped line-by-line text search grep, and SHA-256/SHA-512 hash
• explicit nested-archive access with repeatable --within
• password-file access for encrypted ZIP and 7z archives
• explicit ordered split files with repeatable --volume
• a saved file-list cache (index) you can create, refresh, or delete
• safe full or single-file extract
• extract-all with a parallel-job cap and recursive discovery
• all-or-nothing pack, --dry-run, destination-collision policies, and --delete-source
• verify that checks as it reads
• a format convert that writes a temporary file and only saves it after re-verification
• a built-in local stdio MCP entry point: nine capped read-only tools and six plan-then-execute write tools that need explicit permission
• JSON output with a version number on every structured command

Planned commands and formats are kept in ROADMAP.md and are not presented as currently available.

Supported formats

Detection uses file content. Empty compressed TAR archives use a TAR suffix to distinguish their zero blocks from ordinary binary content. pack uses the output suffix to select the new format.

The current ZIP build enables Stored/Deflate and AES decryption. Metadata listing can still identify a ZIP using another compression method, but reading or verifying that content returns unsupported_operation when the codec is unavailable. RAR is intentionally read-only; see docs/RAR.md for the underlying implementation, licensing, encryption, and native multipart limits.

Install

Choose one public installation channel:

cargo install arcthis --locked
brew install mkynyd/tap/arcthis
npm install -g arcthis
pnpm add -g arcthis

pnpm 11 may hold packages published less than 24 hours ago. On release day, append --config.minimumReleaseAge=0 if it reports ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION.

Prebuilt archives and SHA-256 checksums for Apple Silicon macOS, Intel macOS, and x86_64 Linux are available from the v0.5.1 GitHub Release.

Build from source

Rust 1.98.0 is pinned by rust-toolchain.toml.

RAR support links libarchive statically into release builds. Source builds need libarchive and its development dependencies. On macOS, install libarchive libb2 bzip2 lz4 xz zstd with Homebrew. On Debian/Ubuntu, install libarchive-dev libb2-dev libbz2-dev liblz4-dev liblzma-dev libxml2-dev libzstd-dev zlib1g-dev.

cargo build --release --locked
./target/release/arcthis --help

To install a local checkout into Cargo's binary directory:

cargo install --path . --locked

The default build includes the CLI, library, and local MCP entry point, so every installation channel provides the same commands:

arcthis mcp --allow-root ./archives
# Write tools become visible only with an explicit output policy:
arcthis mcp --allow-root ./archives --allow-output-root ./outputs

Library users who deliberately do not need MCP can disable default features with --no-default-features.

The stdio server pins MCP revision 2025-06-18. archive_read requires an offset and length and returns at most the configured window. Source deletion additionally requires both --allow-source-deletion and delete_source: true in a plan/execute request. See RFC 0003 for the full rules.

MCP defaults to four active calls and 16 MiB per tool response, counting structured and text JSON copies. Oversized or excess concurrent calls return resource_limit. grep --max-result-bytes defaults to 16 MiB across files; MCP clamps this further to its response budget and reports omitted matches with matches_truncated.

Quick start

# Discover before extracting
arcthis inspect archive.zip
arcthis list archive.zip
arcthis tree archive.zip --json

# Read one file directly
arcthis read archive.zip README.md

# Discover and search content before extraction
arcthis find source.tar.zst --glob '**/*.rs' --json
arcthis grep source.tar.zst TODO --glob '**/*.rs' --json
arcthis hash archive.zip model.bin --algorithm sha256

# Browse an inner archive without creating a temporary file
arcthis tree backup.zip --within project.tar.gz --json

# Read an encrypted archive without exposing the password in process arguments
arcthis read secret.7z data.txt --password-file ./password.txt

# Access an explicitly ordered split archive
arcthis inspect dataset.7z.001 --volume dataset.7z.002 --volume dataset.7z.003 --json

# Create or refresh the saved file-list cache
arcthis index dataset.7z --json

# Write a temporary sibling file, then safely save one file
arcthis extract archive.zip README.md --output ./README.md

# Safely extract all files
arcthis extract archive.tar.gz

# Review a destructive batch plan before anything runs
arcthis extract-all ./downloads --recursive --delete-source --dry-run --json

# Create, reopen, verify, and save a new archive
arcthis pack ./project --output project.tar.gz

# Verify every readable file
arcthis verify project.tar.gz --json

# Review the plan, write to a temporary location, verify, then save
arcthis convert project.zip --output project.tar.zst --dry-run --json

See START.md for destination rules, resource limits, JSON formats, exit codes, and complete command guidance.

Safety model

Extraction first checks metadata and paths, rejects links and special files, enforces declared and actual byte/time/ratio limits, writes into a temporary folder on the same filesystem, and saves the result only after every file succeeds. Every write rejects source/destination ancestor overlap before collision handling; recursive batches also protect every discovered archive source. Existing destinations are refused by default; --overwrite, --skip-existing, and --rename are mutually exclusive explicit choices.

Packing writes a temporary sibling archive, finishes it, reopens it through the normal archive interface, verifies every file, and only then saves the requested output. An output inside a directory source, or any source/destination that points to the same place, is rejected. --delete-source runs only after that save, and only when deleting the source cannot remove the destination; dry-runs never write or delete.

Nested access decodes the selected inner file into a size-limited read-only memory buffer; it does not create a temporary file. Conversion writes validated files to a system temporary folder, packs, reopens, and verifies before saving. The saved file-list cache is treated as untrusted input and is invalidated by source size and modification time. Read docs/SECURITY.md for exact guarantees and known limits.

Agent interface

• Successful structured output uses schema_version: "1".
• Results go to stdout; warnings and errors go to stderr.
• Program errors are JSON on stderr when --json is active.
• read always emits raw bytes and rejects --json.
• BrokenPipe is treated as a successful early stop by the reader.
• File metadata explicitly reports path_encoding for non-UTF-8 names.
• File metadata includes stable archive order and lightweight extension-based file-type guesses.
• Non-TTY and JSON output contain no ANSI color decoration.

The public JSON format and error model are documented in docs/CLI.md.

Platform support

v0.5 is developed and tested on macOS and Linux through local tests and a two-platform GitHub Actions workflow, including all-feature MCP coverage. The design avoids Unix-only public interfaces, but Windows is not yet a supported automated-test target.

Development

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo build --release --locked --all-features

Important entry points:

• START.md — detailed user guide
• INDEX.md — concise repository map
• docs/PRODUCT.md — product definition and non-goals
• docs/ARCHITECTURE.md — archive interface and underlying-format design
• docs/SECURITY.md — extraction and lifecycle security
• AGENTS.md — long-lived repository rules for coding agents
• CONTRIBUTING.md — contribution workflow

Roadmap and contributing

The staged format and feature plan is in ROADMAP.md; the six-stage MCP/remote/service/binding program is detailed in docs/V0.5-INTEGRATIONS-PLAN.md. Contributions should preserve unified command behavior, direct read/write, JSON format compatibility, and conservative extraction defaults. Read CONTRIBUTING.md before changing public behavior.

License

arcthis is available under the MIT License. Native and Rust dependency notices relevant to distribution are summarized in THIRD_PARTY_LICENSES.md.