Skip to main content

loom artifacts

Inspect a declared job archive without extracting files. Select an exact run ID and canonical job ID; IDs are never normalized and there is no latest selector.

loom artifacts list <run_id> --job <job-id> --max-members 200
loom artifacts read <run_id> out/report.txt --job <job-id> --encoding text
loom artifacts read <run_id> out/program.bin --job <job-id> --encoding base64 --max-bytes 65536

Both commands return one JSON object. List returns sorted members with path and size_bytes, an archive descriptor (path, format, size_bytes), total_members, returned_members and complete. Its status is published or empty for a valid archive with no members. Read returns member, encoding, body, original returned_bytes, total_bytes and truncated, plus the archive and exact run/job identities.

The archive descriptor describes the currently opened file. Read the producer's publication event for its original writer SHA-256 and compressed/decoded byte counts; ordinary log secret masking applies there.

--max-members defaults to 200 (maximum 1,000). --max-bytes defaults to 65,536 (maximum 1,048,576); zero selects these defaults. Text is the CLI default and requires the entire selected member to be valid UTF-8. It preserves original bytes and ends a truncated prefix at a rune boundary. Base64 supports arbitrary original bytes. Artifacts are not redacted; inspect content within its intended trust boundary.

The shared reader validates the whole archive before returning any result. It only reads .loom/.runtime/artifacts/<run_id>/jobs/<job-id>/artifacts.tar.gz beneath the current repository. Logs are separate. Unsafe paths, symlinks, nonregular entries, duplicate/conflicting names, malformed/truncated archives and resource limit violations fail without a partial body. A missing archive cannot prove whether outputs were skipped, empty or undeclared. Missing run/job errors refer to this artifact namespace, not process liveness.

Inspection supports Linux and macOS. Per-call limits are 256 MiB compressed, 1 GiB decoded including metadata, 10,000 regular members, 4,096 UTF-8 bytes per member path and a private 2 MiB budget per internal tar header traversal. Contained descriptor opens and substitution rechecks do not authenticate archive bytes or continuously freeze the namespace. See the MCP artifact tools for the same data through MCP, and artifact execution guidance for permissions and runtime compatibility.