tzst

Use when the user needs to create, extract, flatten, list, test, install, script, or troubleshoot `tzst` CLI workflows for `.tzst` or `.tar.zst` archives, including compression levels, streaming mode, extraction filters, conflict resolution, JSON output, or standalone binary setup, even if they describe the archive task without naming `tzst`.

name: tzst description: Use when the user needs to create, extract, flatten, list, test, install, script, or troubleshoot `tzst` CLI workflows for `.tzst` or `.tar.zst` archives, including compression levels, streaming mode, extraction filters, conflict resolution, JSON output, or standalone binary setup, even if they describe the archive task without naming `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

附带文件

references/cli-reference.md

# tzst CLI Reference

This reference is for the `tzst` CLI only. It is grounded in the upstream README plus `src/tzst/cli.py`; if those disagree, trust the CLI source.

## Install and Preflight

```bash
tzst --version
tzst --help
uv tool install tzst
pip install tzst
```

If the user wants a standalone binary instead of a Python install, use the release assets at <https://github.com/xixu-me/tzst/releases/latest>.

## Command Matrix

| Goal                    | Command                        | Key flags                                                | Notes                                                                 |
| ----------------------- | ------------------------------ | -------------------------------------------------------- | --------------------------------------------------------------------- |
| Create archive          | `tzst a archive.tzst files...` | `-c`, `-l`, `--level`, `--no-atomic`                     | Aliases: `add`, `create`. Default compression level is `3`.           |
| Extract with paths      | `tzst x archive.tzst`          | `-o`, `--streaming`, `--filter`, `--conflict-resolution` | Preserve directory structure. Preferred default for extraction.       |
| Extract flat            | `tzst e archive.tzst`          | `-o`, `--streaming`, `--filter`, `--conflict-resolution` | Use only when flattening is explicitly wanted. Alias: `extract-flat`. |
| List contents           | `tzst l archive.tzst`          | `-v`, `--streaming`                                      | Alias: `list`.                                                        |
| Test integrity          | `tzst t archive.tzst`          | `--streaming`                                            | Alias: `test`.                                                        |
| Machine-readable output | `tzst --json --no-banner ...`  | `--json`, `--no-banner`                                  | Prefer for scripts and automation.                                    |

## Safety Defaults

- Use `x` before `e` unless the user clearly wants flattened output.
- Keep `--filter data` as the extraction default.
- Keep atomic creation enabled by default. `--no-atomic` is an exception, not the normal path.
- Prefer `--streaming` for large archives or constrained memory.
- For automated extraction, set an explicit `--conflict-resolution` value instead of relying on the interactive default.

## Security Filters

| Filter          | Use When                                                          | Notes                                                     |
| --------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |
| `data`          | Default choice for normal extraction                              | Safest option. Good for untrusted archives.               |
| `tar`           | The user needs standard tar compatibility                         | Less strict than `data`, but still safer than full trust. |
| `fully_trusted` | Only when the archive source is explicitly and completely trusted | Never recommend this by default.                          |

## Conflict Resolution

Use these values with `x` or `e`:

- `replace`
- `skip`
- `replace_all`
- `skip_all`
- `auto_rename`
- `auto_rename_all`
- `ask`

Guidance:

- `ask` is the interactive default for humans.
- For automation, prefer an `_all` value so the command cannot block on prompts.
- When using `--json`, do not rely on `ask`; choose an explicit non-interactive value.

## Copy-Paste Examples

```bash
# Create an archive with the default atomic behavior
tzst a backup.tzst documents/ photos/ config.json

# Create with higher compression
tzst a backup.tzst documents/ -l 10

# Extract while preserving paths
tzst x backup.tzst -o restore/

# Extract specific members
tzst x backup.tzst config.json docs/readme.md -o restore/

# Extract flat into one directory
tzst e backup.tzst -o flat/

# List contents with details
tzst l backup.tzst -v

# Test a large archive with streaming
tzst t backup.tzst --streaming

# Extract with the safest filter and streaming mode
tzst x backup.tzst -o restore/ --filter data --streaming

# Automated extraction with an explicit conflict policy
tzst x backup.tzst -o restore/ --conflict-resolution replace_all

# Machine-readable list output for scripts
tzst --json --no-banner l backup.tzst

# Machine-readable extract output with non-interactive conflict handling
tzst --json --no-banner x backup.tzst -o restore/ --conflict-resolution auto_rename_all
```

## Exit Codes

| Exit Code | Meaning                                                           |
| --------- | ----------------------------------------------------------------- |
| `0`       | Success                                                           |
| `1`       | General operation error such as missing files or archive failures |
| `2`       | Argument parsing or invalid flag error                            |
| `130`     | Interrupted by the user                                           |