CLI API

The command-line interface module provides comprehensive functionality for the tzst CLI tool, including argument parsing, command execution, and interactive features.

Command-line interface for tzst.

tzst.cli.cmd_add(args) → int[source]

Command handler for creating/adding to archives.

Processes the ‘add’, ‘create’, or ‘a’ CLI commands to create new tzst archives with the specified files and directories. Uses atomic file operations by default to ensure data integrity.

Parameters:

args – Parsed command line arguments containing: - archive (str): Path to the archive file to create - files (list[str]): List of files/directories to add - compression_level (int, optional): Compression level 1-22 - no_atomic (bool, optional): Disable atomic file operations

Returns:

Exit code (0 for success, non-zero for failure)

0: Success
1: File not found, invalid parameters, or archive operation failed
130: Operation interrupted by user (Ctrl+C)

Return type:

int

Note

This function uses atomic file operations by default, creating the archive in a temporary file first, then atomically moving it to the final location to prevent incomplete archives.

See also

tzst.create_archive(): The underlying function for archive creation TzstArchive.add(): The core method for adding files to archives

tzst.cli.cmd_extract_flat(args) → int[source]

Command handler for flat extraction without directory structure.

Processes the ‘extract-flat’ or ‘e’ CLI commands to extract files from tzst archives without preserving directory structure (all files extracted to a single directory).

Parameters:

args – Parsed command line arguments containing: - archive (str): Path to the archive file to extract - output (str, optional): Output directory path - files (list[str], optional): Specific files to extract - streaming (bool, optional): Use streaming mode for large archives - filter (str, optional): Security filter (‘data’, ‘tar’, ‘fully_trusted’)

Returns:

Exit code (0 for success, non-zero for failure)

0: Success
1: File not found, decompression failed, or archive operation failed
130: Operation interrupted by user (Ctrl+C)

Return type:

int

Warning

Flat extraction may cause filename conflicts if multiple files have the same name but are in different directories within the archive.

See also

tzst.extract_archive(): The underlying function for extraction TzstArchive.extract(): The core method for extracting from archives cmd_extract_full(): For extraction with directory structure

tzst.cli.cmd_extract_full(args) → int[source]

Command handler for extracting archives with full directory structure.

Processes the ‘extract’ or ‘x’ CLI commands to extract files from tzst archives while preserving the original directory structure.

Parameters:

args – Parsed command line arguments containing: - archive (str): Path to the archive file to extract - output (str, optional): Output directory path - files (list[str], optional): Specific files to extract - streaming (bool, optional): Use streaming mode for large archives - filter (str, optional): Security filter (‘data’, ‘tar’, ‘fully_trusted’)

Returns:

Exit code (0 for success, non-zero for failure)

0: Success
1: File not found, decompression failed, or archive operation failed
130: Operation interrupted by user (Ctrl+C)

Return type:

int

Note

Uses the ‘data’ security filter by default for safe extraction from untrusted sources. Streaming mode is recommended for archives > 100MB.

See also

tzst.extract_archive(): The underlying function for extraction TzstArchive.extract(): The core method for extracting from archives cmd_extract_flat(): For flat extraction without directory structure

tzst.cli.cmd_list(args) → int[source]

Command handler for listing archive contents.

Processes the ‘list’ or ‘l’ CLI commands to display the contents of tzst archives. Supports both simple and verbose listing modes.

Parameters:

args – Parsed command line arguments containing: - archive (str): Path to the archive file to list - verbose (bool, optional): Show detailed file information - streaming (bool, optional): Use streaming mode for large archives

Returns:

Exit code (0 for success, non-zero for failure)

0: Success
1: File not found, decompression failed, or archive operation failed
130: Operation interrupted by user (Ctrl+C)

Return type:

int

Note

Verbose mode displays file permissions, sizes, modification times, and other metadata. Streaming mode is recommended for archives > 100MB.

See also

tzst.list_archive(): The underlying function for listing contents TzstArchive.list(): The core method for listing archive contents

tzst.cli.cmd_test(args) → int[source]

Command handler for testing archive integrity.

Processes the ‘test’ or ‘t’ CLI commands to verify the integrity of tzst archives by attempting to read all files and checking for corruption.

Parameters:

args – Parsed command line arguments containing: - archive (str): Path to the archive file to test - streaming (bool, optional): Use streaming mode for large archives

Returns:

Exit code (0 for success, non-zero for failure)

0: Archive passed integrity test
1: Archive failed integrity test, file not found, or operation failed
130: Operation interrupted by user (Ctrl+C)

Return type:

int

Note

This command verifies that the archive can be read and all files can be decompressed without errors. Streaming mode is recommended for archives > 100MB to reduce memory usage.

See also

tzst.test_archive(): The underlying function for integrity testing TzstArchive.test(): The core method for testing archive integrity

tzst.cli.cmd_version(args) → int[source]

Command handler for version display.

Returns:: Exit code (always 0)
Return type:: int

tzst.cli.create_parser() → ArgumentParser[source]

Create and configure the command-line argument parser.

Sets up the argparse ArgumentParser with all subcommands and their respective arguments for the tzst CLI interface. Includes comprehensive help text and command reference documentation.

Returns:: Configured parser ready for argument parsing
Return type:: argparse.ArgumentParser

Note

The parser is configured with RawDescriptionHelpFormatter to preserve formatting in the epilog help text, and includes detailed command reference and security notes.

Commands Created:

a, add, create: Archive creation with compression levels
x, extract: Full extraction with directory structure
e, extract-flat: Flat extraction without directories
l, list: Archive content listing
t, test: Archive integrity testing

See also

main(): The main entry point that uses this parser

tzst.cli.format_size(size: int) → str[source]

Format file size in human-readable format.

Converts byte values to human-readable format using standard units (B, KB, MB, GB, TB, PB) with appropriate decimal places.

Parameters:: size (int) – Size in bytes to format
Returns:: Formatted size string with units (e.g., “1.5 KB”, “2.3 GB”)
Return type:: str

Examples

>>> format_size(1024)
'  1.0 KB'
>>> format_size(1536)
'  1.5 KB'
>>> format_size(2048576)
'  2.0 MB'

tzst.cli.main(argv: list[str] | None = None) → int[source]

Main entry point for the tzst command-line interface.

Processes command-line arguments and dispatches to appropriate command handlers. Displays the version banner and provides error handling for the overall CLI execution.

Parameters:

argv (list[str] | None, optional) – Command line arguments to parse. If None, uses sys.argv. Defaults to None.

Returns:

Exit code for the program

0: Success
1: Invalid compression level, filter, or command error
2: Argument parsing error (help, unknown options)
Other codes: Specific to individual command handlers

Return type:

int

Note

This function serves as the console script entry point defined in pyproject.toml. It displays the version banner before executing any commands.

See also

create_parser(): Creates the argument parser used by this function

tzst.cli.print_banner() → None[source]

Print the version and copyright banner.

Displays the tzst version number and copyright information to stdout. Used as a header for CLI operations.

Returns:: None

tzst.cli.validate_compression_level(value: str) → int[source]

Validate and return compression level.

Parameters:: value – String value from command line
Returns:: Valid compression level (1-22)
Return type:: int
Raises:: argparse.ArgumentTypeError – If value is not a valid compression level

Overview

The tzst CLI provides a powerful command-line interface for archive operations with intuitive commands and comprehensive options. The interface is designed for both interactive use and scripting, with robust error handling and user-friendly output.

Core Commands

Command	Aliases	Description	Streaming Support
`a`	`add`, `create`	Create or add to archive	N/A
`x`	`extract`	Extract with full paths	`--streaming`
`e`	`extract-flat`	Extract without directory structure	`--streaming`
`l`	`list`	List archive contents	`--streaming`
`t`	`test`	Test archive integrity	`--streaming`

Key Features

Intuitive Commands: Simple, memorable command aliases (a, x, e, l, t)
Streaming Support: Memory-efficient processing for large archives
Interactive Conflict Resolution: User-friendly prompts for handling file conflicts
Comprehensive Options: Fine-grained control over compression, extraction, and security
Cross-Platform: Consistent behavior across Windows, macOS, and Linux

Main Functions

main

tzst.cli.main(argv: list[str] | None = None) → int[source]

Main entry point for the tzst command-line interface.

Processes command-line arguments and dispatches to appropriate command handlers. Displays the version banner and provides error handling for the overall CLI execution.

Parameters:

argv (list[str] | None, optional) – Command line arguments to parse. If None, uses sys.argv. Defaults to None.

Returns:

Exit code for the program

0: Success
1: Invalid compression level, filter, or command error
2: Argument parsing error (help, unknown options)
Other codes: Specific to individual command handlers

Return type:

int

Note

This function serves as the console script entry point defined in pyproject.toml. It displays the version banner before executing any commands.

See also

create_parser(): Creates the argument parser used by this function

The main entry point for the CLI application. Handles argument parsing, command execution, and comprehensive error reporting.

Key Features:

Robust argument validation and error handling
Support for all archive operations
Consistent exit codes for scripting
User-friendly error messages

Exit Codes:

0: Success
1: General error (file not found, archive corruption, etc.)
2: Argument parsing error
130: Interrupted by user (Ctrl+C)

create_parser

tzst.cli.create_parser() → ArgumentParser[source]

Create and configure the command-line argument parser.

Sets up the argparse ArgumentParser with all subcommands and their respective arguments for the tzst CLI interface. Includes comprehensive help text and command reference documentation.

Returns:: Configured parser ready for argument parsing
Return type:: argparse.ArgumentParser

Note

The parser is configured with RawDescriptionHelpFormatter to preserve formatting in the epilog help text, and includes detailed command reference and security notes.

Commands Created:

a, add, create: Archive creation with compression levels
x, extract: Full extraction with directory structure
e, extract-flat: Flat extraction without directories
l, list: Archive content listing
t, test: Archive integrity testing

See also

main(): The main entry point that uses this parser

Creates and configures the comprehensive argument parser for the CLI interface.

Supported Arguments:

Global: --version, --help
Archive Creation: -l/--level, --no-atomic
Extraction: -o/--output, --streaming, --filter, --conflict-resolution
Listing: -v/--verbose, --streaming
Testing: --streaming

Command Handlers

The CLI implements dedicated command handlers for each operation, providing specialized functionality and error handling.

Archive Creation Commands

cmd_add

Creates new archives from files and directories with configurable compression and atomic operations.

Features:

Configurable compression levels (1-22)
Atomic file operations (default) for safe creation
Recursive directory processing
Path validation and normalization

Usage Examples:

# Basic archive creation
tzst a backup.tzst documents/ photos/

# High compression with atomic disabled
tzst a backup.tzst files/ -l 15 --no-atomic

Extraction Commands

cmd_extract_full

Extracts archives preserving complete directory structure with advanced conflict resolution.

Features:

Preserves full directory paths
Multiple conflict resolution strategies
Security filters for safe extraction
Selective file extraction
Streaming mode for large archives

cmd_extract_flat

Extracts archives flattening all files to a single directory, useful for consolidating files.

Features:

Flattens directory structure
Automatic conflict resolution for filename collisions
Preserves file content while simplifying structure
Same security and streaming features as full extraction

Management Commands

cmd_list

Lists archive contents with optional detailed information and streaming support.

Features:

Simple or verbose listing modes
Human-readable file sizes
Modification timestamps
Streaming mode for memory efficiency

cmd_test

Tests archive integrity and validity with comprehensive error reporting.

Features:

Complete archive validation
Streaming mode support
Detailed error reporting
Exit codes for automated testing

cmd_version

Displays version information and system details.

Utility Functions

format_size

tzst.cli.format_size(size: int) → str[source]

Format file size in human-readable format.

Converts byte values to human-readable format using standard units (B, KB, MB, GB, TB, PB) with appropriate decimal places.

Parameters:: size (int) – Size in bytes to format
Returns:: Formatted size string with units (e.g., “1.5 KB”, “2.3 GB”)
Return type:: str

Examples

>>> format_size(1024)
'  1.0 KB'
>>> format_size(1536)
'  1.5 KB'
>>> format_size(2048576)
'  2.0 MB'

Formats file sizes in a human-readable format (bytes, KB, MB, GB).

validate_compression_level

tzst.cli.validate_compression_level(value: str) → int[source]

Validate and return compression level.

Parameters:: value – String value from command line
Returns:: Valid compression level (1-22)
Return type:: int
Raises:: argparse.ArgumentTypeError – If value is not a valid compression level

Validates compression level arguments and converts them to integers.

Interactive Features

The CLI includes interactive conflict resolution for file extraction conflicts, allowing users to choose how to handle existing files during extraction operations.

Conflict Resolution Options

Replace: Overwrite the existing file
Skip: Keep the existing file, skip extraction
Replace All: Apply replace to all subsequent conflicts
Skip All: Apply skip to all subsequent conflicts
Auto-rename All: Automatically rename conflicting files
Exit: Stop extraction process

Security Considerations

The CLI implements multiple security filters for safe extraction:

data filter (default): Safest option, blocks potentially dangerous archive members
tar filter: Preserves more tar features while maintaining basic security
fully_trusted filter: No restrictions, use only with completely trusted archives

Performance Options

Streaming Mode: Use --streaming for memory-efficient processing of large archives (>100MB)
Compression Levels: Choose from 1 (fastest) to 22 (maximum compression)
Atomic Operations: Default behavior uses temporary files for safe archive creation

CLI API

Overview

Core Commands

Key Features

Main Functions

main

create_parser

Command Handlers

Archive Creation Commands

cmd_add

Extraction Commands

cmd_extract_full

cmd_extract_flat

Management Commands

cmd_list

cmd_test

cmd_version

Utility Functions

print_banner

format_size

validate_compression_level

Interactive Features

Conflict Resolution Options

Security Considerations

Performance Options