tzst

Use this skill for the

tzst

command-line interface. Default to execution when the user clearly wants a real archive action and the required paths or archive names are already known.

This skill is CLI-only. If the user is asking about Python code such as

from tzst import ...

, treat that as a general Python library or API documentation task instead of using this skill as the main guide.

When to Use

Use this skill when the user:

mentions
```
.tzst
```
or
```
.tar.zst
```
archives
wants to create, extract, flatten, list, or test a
```
tzst
```
archive
needs help installing
```
tzst
```
or choosing CLI flags
wants machine-readable
```
tzst
```
output for scripting or automation
needs safe conflict handling or extraction filter guidance

Do not use this skill for generic

tar

zip

, or Python API questions unless

tzst

is actually part of the request.

Preflight

Check whether
```
tzst
```
is available with
```
tzst --version
```
or
```
tzst --help
```
.
If it is missing, prefer one of these installation paths:
- ```
uv tool install tzst
```
- ```
pip install tzst
```
- a standalone release binary from https://github.com/xixu-me/tzst/releases/latest when the user does not want a Python installation
Re-run
```
tzst --version
```
or
```
tzst --help
```
before doing real work.

Workflow

Decide whether the request is execution or guidance. Requests like "archive these files", "extract this backup", "list what is inside", "test this archive", or "install tzst" are execution intent.
Choose the command that matches the request:
- ```
a
```
  ,
```
add
```
  ,
```
create
```
  for archive creation
- ```
x
```
  ,
```
extract
```
  for normal extraction with directory structure preserved
- ```
e
```
  ,
```
extract-flat
```
  only when the user explicitly wants flattened output
- ```
l
```
  ,
```
list
```
  for archive inspection
- ```
t
```
  ,
```
test
```
  for integrity checks
If the user wants to extract only a few members and the member names are uncertain, list first.
Load
```
references/cli-reference.md
```
when you need the command matrix, exact flag names, or copy-paste examples.

Safe Defaults

Prefer
```
x
```
over
```
e
```
unless flattening is explicitly requested.
Keep
```
--filter data
```
as the default extraction mode.
Use
```
--filter tar
```
only when the user needs standard tar-style compatibility.
Use
```
--filter fully_trusted
```
only when the user explicitly says the archive source is completely trusted.
Keep atomic archive creation enabled. Only reach for
```
--no-atomic
```
when the user explicitly wants it.
Prefer
```
--streaming
```
for large archives or memory-constrained environments.
For automation or pipelines, prefer
```
tzst --json --no-banner ...
```
.
For automated extraction, require an explicit non-interactive
```
--conflict-resolution
```
choice such as
```
replace_all
```
,
```
skip_all
```
, or
```
auto_rename_all
```
.
Do not combine
```
--json
```
with interactive conflict prompting.

Scripting Notes

Put global flags before the subcommand in examples, such as
```
tzst --json --no-banner l archive.tzst
```
.
Use exit codes in scripts:
```
0
```
for success,
```
1
```
for operation errors,
```
2
```
for argument parsing errors, and
```
130
```
for interruption.
When archive naming matters, tell the user that
```
tzst
```
may normalize a creation target to
```
.tzst
```
or
```
.tar.zst
```
.

Common Mistakes

Using
```
e
```
when the user expected the original directory structure to be preserved
Recommending
```
fully_trusted
```
for archives from an unknown or untrusted source
Forgetting an explicit conflict strategy for non-interactive extraction
Treating a Python API question as a CLI question
Guessing flags from
```
tar
```
habits instead of checking the bundled reference or the installed CLI help

tzst

NPX Install

Tags

SKILL.md Content

tzst

When to Use

Preflight

Workflow

Safe Defaults

Scripting Notes

Common Mistakes