### Televault Quick Start Guide

Source: https://github.com/yahyatoubali/televault/blob/dev/README.md

Follow these steps to get started with Televault: log in, set up your storage, and perform basic file operations like push, list, and download.

```bash
# 1) Login (will prompt for API credentials from https://my.telegram.org)
tvt login

# 2) Set up storage (interactive — validates channel, sends test message)
tvt setup

# 3) Upload
tvt push photo.jpg

# 5) List
tvt ls

# 6) Download
tvt pull photo.jpg

# 7) Stream to stdout
tvt cat photo.jpg > photo_copy.jpg

# 8) Preview without full download
tvt preview photo.jpg

# 9) Check channel info
tvt channel
```

--------------------------------

### Quick Start Development Setup

Source: https://github.com/yahyatoubali/televault/blob/dev/CONTRIBUTING.md

Clone the repository, set up a virtual environment, activate it, and install the project with development dependencies.

```bash
git clone https://github.com/YahyaToubali/televault.git
cd televault
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev,fuse,webdav,preview]"
```

--------------------------------

### Local Documentation Preview

Source: https://github.com/yahyatoubali/televault/blob/dev/CONTRIBUTING.md

Install necessary packages and start a local development server to preview documentation changes. Changes are reflected live.

```bash
pip install -e ".[dev]" && pip install mkdocs-material
mkdocs serve
```

--------------------------------

### Install TeleVault

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/index.md

Install the TeleVault command-line tool using pipx. Ensure you have Python 3.11+ installed.

```bash
# Install
pipx install televault
```

--------------------------------

### Install Televault with Preview Support

Source: https://github.com/yahyatoubali/televault/blob/dev/README.md

Installs Televault with image preview functionality, which requires the Pillow library.

```bash
pipx install televault[preview]
```

--------------------------------

### Install Televault

Source: https://github.com/yahyatoubali/televault/blob/dev/README.md

Installs the core Televault package using pipx. Ensure you have Python 3.11+ installed.

```bash
pipx install televault
```

--------------------------------

### Install TeleVault with WebDAV support

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/virtualization.md

Install the necessary package for serving TeleVault over WebDAV. This command installs Televault along with its WebDAV dependencies.

```bash
pipx install televault[webdav]
```

--------------------------------

### Install and Login TeleVault

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/index.md

Install TeleVault using pipx and log in to your Telegram account to authorize the application.

```bash
$ pipx install televault
$ tvt login
```

--------------------------------

### Install TeleVault with FUSE support

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/virtualization.md

Install the necessary package for FUSE mounting. This command installs Televault along with its FUSE dependencies.

```bash
pipx install televault[fuse]
```

--------------------------------

### Clone and Set Up Televault Development Environment

Source: https://github.com/yahyatoubali/televault/blob/dev/README.md

Clone the repository, create a virtual environment, activate it, and install Televault with development dependencies.

```bash
git clone https://github.com/YahyaToubali/televault.git
cd televault
python -m venv .venv
source .venv/bin/activate
pipx install -e ".[dev,fuse,webdav,preview]"
```

--------------------------------

### Install CLI Tool

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

Defines the command-line interface scripts for the TeleVault project.

```toml
[project.scripts]
tvt        = "televault.cli:main"
televault  = "televault.cli:main"
```

--------------------------------

### Televault Pipeable I/O Examples

Source: https://github.com/yahyatoubali/televault/blob/dev/README.md

Demonstrates how to use Televault with standard input/output and pipe commands like `jq` for processing JSON output.

```bash
echo "hello" | tvt push - --name note.txt
cat config.json | tvt push - --name config.json
mysqldump mydb | tvt push - --name backup.sql

tvt cat config.json | jq '.database'
tvt ls --json | jq '.[].name'
tvt find "backup" --json | jq '.[].size'
```

--------------------------------

### Start TeleVault WebDAV server on default host and port

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/virtualization.md

Start the TeleVault WebDAV server. By default, it binds to all available network interfaces (0.0.0.0) and listens on port 8080.

```bash
# Default: http://0.0.0.0:8080
tvt serve
```

--------------------------------

### Start TeleVault WebDAV server on custom host and port

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/virtualization.md

Start the TeleVault WebDAV server on a custom host and port. This allows you to specify the network interface and port number for accessibility.

```bash
# Custom host/port
tvt serve --host 192.168.1.100 --port 9090
```

--------------------------------

### Setup TeleVault Storage Channel

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/index.md

Initialize the storage channel within your Telegram account. This process is interactive.

```bash
# Setup storage channel (interactive)
tvt setup
```

--------------------------------

### Install FUSE requirements on Linux

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/virtualization.md

Install the necessary FUSE and libfuse2 packages on Linux systems. These are prerequisites for mounting TeleVault using FUSE.

```bash
# Linux
sudo apt install fuse libfuse2
```

--------------------------------

### Televault Auto-Backup Schedule Commands

Source: https://github.com/yahyatoubali/televault/blob/dev/README.md

Commands for creating, installing, and listing backup schedules, as well as watching a directory for changes to trigger backups.

```bash
tvt schedule create /data --name daily --interval daily
tvt schedule install daily     # systemd timer (Linux)
tvt schedule list
tvt watch --path /data        # Watch for changes
```

--------------------------------

### Start TeleVault WebDAV server in read-only mode

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/virtualization.md

Start the TeleVault WebDAV server in read-only mode. This prevents any modifications to the vault through the WebDAV interface.

```bash
# Read-only
tvt serve --read-only
```

--------------------------------

### Install FUSE requirements on macOS

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/virtualization.md

Install macFUSE from the official website. This is a requirement for using FUSE mounts on macOS.

```bash
# macOS
# Install macFUSE from https://macfuse.io/
```

--------------------------------

### Launch Interactive TUI

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/commands.md

Starts the Televault interactive terminal user interface. This feature is currently in beta.

```bash
tvt tui
```

--------------------------------

### Delete Sequence Steps

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/security.md

Details the steps for deleting a file, starting with removing the file from the index, then deleting associated messages. This ensures safety against crashes during deletion.

```plaintext
1. Remove file from index first
2. Read metadata to collect chunk message IDs
3. Delete all messages (metadata + chunks)
```

--------------------------------

### JSON Output with jq

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/commands.md

Demonstrates how to use the `--json` flag with various Televault commands and pipe the output to `jq` for structured data processing.

```bash
tvt ls --json | jq '.[].name'
```

```bash
tvt stat --json | jq '.total_files'
```

```bash
tvt info photo.jpg --json | jq '.size'
```

```bash
tvt find report --json | jq 'length'
```

--------------------------------

### Running Full Test Suite

Source: https://github.com/yahyatoubali/televault/blob/dev/CONTRIBUTING.md

Execute all tests in the project to ensure the codebase is stable. Use the -v flag for verbose output.

```bash
pytest tests/ -v
```

--------------------------------

### Televault Virtual Drive and Server Commands

Source: https://github.com/yahyatoubali/televault/blob/dev/README.md

Commands to mount Televault as a FUSE virtual drive or run it as a WebDAV server for on-demand streaming and remote access.

```bash
# FUSE mount with on-demand streaming
tvt mount -m ~/televault-drive

# WebDAV server
tvt serve --host 0.0.0.0 --port 8080
```

--------------------------------

### Televault Backup and Restore Commands

Source: https://github.com/yahyatoubali/televault/blob/dev/README.md

Commands for creating, listing, restoring, pruning, and verifying backups. Use `--incremental` for incremental backups and `--keep-daily`/`--keep-weekly` for pruning policies.

```bash
tvt backup create /data --name daily
tvt backup create /data --name incr --incremental
tvt backup list
tvt backup restore <id> --output /restore
tvt backup prune --keep-daily 7 --keep-weekly 4
tvt backup verify <id>
```

--------------------------------

### Televault Core Commands Reference

Source: https://github.com/yahyatoubali/televault/blob/dev/README.md

A comprehensive list of Televault's core commands for file management, searching, and vault statistics. Use `--json` for machine-readable output.

```bash
tvt push <file>              # Upload a file (use - for stdin)
tvt pull <file>              # Download (use -o - for stdout)
tvt ls [--json]              # List files
tvt cat <file>               # Stream file to stdout
tvt preview <file>           # Preview without full download
tvt find <query> [--json]    # Search files
tvt info <file> [--json]     # Detailed file info
tvt stat [--json]            # Vault statistics
tvt rm <file>                # Delete file
tvt verify <file>            # Verify integrity
tvt gc [--force]             # Garbage collection (dry-run by default)
tvt whoami                   # Show account info
tvt login                    # Authenticate
tvt setup                    # Configure channel (interactive)
tvt channel                  # Show channel info
tvt tui                      # Launch terminal UI (beta)
```

--------------------------------

### Upload Files with TeleVault

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/index.md

Upload individual files or recursively upload entire directories to TeleVault storage.

```bash
# Upload
tvt push photo.jpg
tvt push --recursive /data/documents
```

--------------------------------

### Run Televault Tests and Linting

Source: https://github.com/yahyatoubali/televault/blob/dev/README.md

Execute all project tests using pytest and check code quality with Ruff.

```bash
pytest tests/ -v          # Run 157 tests
ruff check src/           # Lint
```

--------------------------------

### Configure Parallelism and Chunk Size

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/hardware.md

Tune upload/download parallelism and chunk size in the Televault configuration file. Adjust these settings based on your system's RAM, network bandwidth, and stability.

```json
{
  "parallel_uploads": 8,
  "parallel_downloads": 10,
  "chunk_size": 268435456,
  "max_retries": 3,
  "retry_delay": 1.0
}
```

--------------------------------

### Manage Backup Schedules

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/commands.md

Commands to list, run, delete, and manage systemd timers for backup schedules.

```bash
tvt schedule list
```

```bash
tvt schedule run <name>
```

```bash
tvt schedule delete <name>
```

```bash
tvt schedule install <name>
```

```bash
tvt schedule uninstall <name>
```

```bash
tvt schedule show-systemd <name>
```

--------------------------------

### Create Backup Schedule

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/commands.md

Use this command to create a new backup schedule. You can specify a directory, a name, and backup intervals (daily, weekly, monthly).

```bash
tvt schedule create <dir> --name <n>
```

```bash
tvt schedule create --interval daily
```

```bash
tvt schedule create --incremental
```

--------------------------------

### Download Files with TeleVault

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/index.md

Download files from TeleVault storage. You can specify an output directory using the `-o` flag.

```bash
# Download
tvt pull photo.jpg
tvt pull photo.jpg -o /tmp/photo.jpg
```

--------------------------------

### Televault Upload Encryption Pipeline

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/engine.md

Illustrates the steps involved in encrypting and uploading a file, from chunking to final upload.

```text
Original File
      │
      ▼
   Chunker (256 MB slices)
      │
      ▼
   BLAKE3 hash (original_hash)
      │
      ▼
   zstd Compression (level 3)
   ── skipped for incompressible extensions
      │
      ▼
   AES-256-GCM Encryption
   ── scrypt(password, salt) → 32-byte key
   ── 16-byte salt + 12-byte nonce = 28-byte header
   ── ciphertext + 16-byte auth tag
   ── overhead: 44 bytes per chunk
      │
      ▼
   BLAKE3 hash of encrypted data (ChunkInfo.hash)
      │
      ▼
   Upload as Telegram file message (reply to metadata)
```

--------------------------------

### Key Derivation using scrypt

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/security.md

Demonstrates the scrypt function for deriving a 256-bit encryption key from a user password and a random salt. The parameters N, r, and p are chosen for a balance of security and performance.

```python
key = scrypt(
    password=user_password,
    salt=random_16_bytes,
    N=131072,      # 2^17
    r=8,
    p=1,
    dklen=32       # 256-bit key
)
```

--------------------------------

### List Files in TeleVault

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/index.md

List the files stored in your TeleVault. The `--json` flag outputs the list in JSON format, which can be piped to tools like `jq`.

```bash
# List
tvt ls
tvt ls --json | jq '.[].name'
```

--------------------------------

### Push a File to TeleVault

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/index.md

Upload a file to your TeleVault storage. The `--recursive` flag can be used for directories.

```bash
$ tvt push secret.tar.gz
```

--------------------------------

### Upload Sequence Steps

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/security.md

Outlines the steps involved in the file upload process, including metadata upload, chunk uploads, cleanup on failure, and metadata update. This sequence is designed to be safe against crashes.

```plaintext
1. Upload metadata message → get `metadata_msg_id`
2. Upload all chunks in parallel
3. On failure: delete all uploaded chunks + metadata (cleanup)
4. Update metadata with chunk info
5. Save index (3 retries with backoff)
```

--------------------------------

### Upload from Stdin

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/commands.md

Pipes content from standard input to the `tvt push` command, allowing for direct uploads of file content.

```bash
cat secret.txt | tvt push - --name secret.txt
```

--------------------------------

### FUSE Mount Architecture Overview

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/virtualization.md

This diagram illustrates the on-demand chunk streaming process for FUSE mounts. It shows how applications read data, and how the FUSE driver fetches, caches, and decrypts necessary chunks.

```text
Application reads bytes 0-4096 from file.jpg
    │
    ▼
FUSE getattr → cached metadata (30s TTL)
    │
    ▼
FUSE open → prefetch first 3 chunks into LRU cache
    │
    ▼
FUSE read → fetch_range(0, 4096)
    │
    ▼
ChunkCache.fetch_chunk(0) → download from Telegram
    │
    ▼
Decrypt → Decompress → Return bytes 0-4096
```

--------------------------------

### Running Tests with Coverage

Source: https://github.com/yahyatoubali/televault/blob/dev/CONTRIBUTING.md

Execute the test suite and generate a code coverage report. This helps identify areas of the code not exercised by tests.

```bash
pytest tests/ -v --cov=televault
```

--------------------------------

### Enable Low-Resource Mode

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/hardware.md

Use the --low-resource flag with any Televault command to reduce memory and CPU usage. This is ideal for systems with limited RAM or on single-board computers.

```bash
tvt push large_file.iso --low-resource
tvt pull large_file.iso --low-resource --resume
```

--------------------------------

### Reading from stdin with tvt push

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

Use this command to read data from standard input and push it to Televault.

```bash
tvt push -
```

--------------------------------

### Login to TeleVault

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/index.md

Log in to your TeleVault account. This command will prompt for your Telegram API credentials.

```bash
# Login — will prompt for API credentials from https://my.telegram.org
tvt login
```

--------------------------------

### Run Development Checks

Source: https://github.com/yahyatoubali/televault/blob/dev/CONTRIBUTING.md

Execute tests and linting checks to ensure code quality before committing. All tests must pass, and there should be zero lint errors.

```bash
pytest tests/ -v          # All 168 tests must pass
ruff check src/televault/ # Zero lint errors
```

--------------------------------

### Global CLI Flags

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/commands.md

Common flags to control logging verbosity, display version, or show help information.

```bash
tvt -v, --verbose
```

```bash
tvt --debug
```

```bash
tvt --version
```

```bash
tvt --help
```

--------------------------------

### Running Single Test File

Source: https://github.com/yahyatoubali/televault/blob/dev/CONTRIBUTING.md

Execute tests for a specific file, such as 'test_chunker.py', for focused testing. Use the -v flag for verbose output.

```bash
pytest tests/test_chunker.py -v
```

--------------------------------

### Televault Project Structure

Source: https://github.com/yahyatoubali/televault/blob/dev/README.md

This outlines the directory and file structure of the Televault project. It includes the main source directory 'src/televault' with various modules for core functionality, Telegram integration, crypto, compression, and more, as well as a 'tests' directory.

```tree
src/televault/
├── __init__.py        # Version
├── cli.py             # Click CLI — command dispatch, friendly errors, progress display
├── core.py            # TeleVault class — upload, download, list, search, stream
├── telegram.py        # TelegramVault — MTProto client, channel ops, index, compression
├── models.py          # FileMetadata, ChunkInfo, VaultIndex, TransferProgress
├── chunker.py         # File splitting/merging, ChunkWriter, BLAKE3, async hashing
├── crypto.py          # AES-256-GCM, scrypt KDF, streaming encrypt/decrypt
├── compress.py        # zstd compression, extension-based skip
├── config.py          # Config dataclass, atomic persistence, directory resolution
├── retry.py           # Exponential backoff, FloodWait handling, @with_retry decorator
├── backup.py          # BackupEngine — snapshot CRUD, prune, verify
├── snapshot.py        # Snapshot, SnapshotFile, SnapshotIndex, RetentionPolicy
├── fuse.py            # TeleVaultFuse — on-demand streaming with LRU cache
├── webdav.py          # WebDAV server (aiohttp)
├── preview.py         # PreviewEngine — terminal previews from headers
├── watcher.py         # FileWatcher — polling, BLAKE2, exclude patterns
├── schedule.py        # Schedule CRUD, systemd timers, cron generation
├── gc.py              # Orphan message detection and cleanup
├── utils.py           # Shared utilities (format_size, format_speed)
├── logging.py         # RotatingFileHandler setup
└── tui.py             # Textual TUI — file browser, detail panel (beta)

tests/
├── test_chunker.py
├── test_compress.py
├── test_crypto.py
├── test_fuse.py
├── test_models.py
├── test_models_v2.py
├── test_preview.py
├── test_retry.py
├── test_schedule.py
├── test_snapshot.py
├── test_telegram_helpers.py
└── test_webdav.py
```

--------------------------------

### JSON output for Televault commands

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

These commands output results in JSON format, useful for scripting and integration.

```bash
tvt ls --json
```

```bash
tvt stat --json
```

```bash
tvt info --json
```

```bash
tvt find --json
```

--------------------------------

### Scrypt Key Derivation Parameters

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/engine.md

Specifies the parameters used for Scrypt key derivation, including the cost factors N, r, and p, and the output size.

```plaintext
scrypt(password, salt):
  N = 2^17 (131072)
  r = 8
  p = 1
  output = 32 bytes (256-bit AES key)
```

--------------------------------

### Upload Encryption Pipeline

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

Describes the steps involved in encrypting and uploading file chunks. Compression is skipped for incompressible file types.

```plaintext
Original File
     |
     v
  Chunker (256 MB slices; 32 MB in low-resource mode)
     |
     v
  Per-chunk: compute original_hash via BLAKE3 (threaded, non-blocking)
     |
     v
  Optional Compression (zstd level 3)
  -- skipped for incompressible extensions
     |
     v
  Encryption (AES-256-GCM)
  -- scrypt(password, salt) -> 32-byte key
  -- 16-byte random salt + 12-byte random nonce = 28-byte header
  -- GCM produces ciphertext + 16-byte authentication tag
  -- total overhead per chunk: 44 bytes (28 header + 16 tag)
     |
     v
  Compute hash (BLAKE3 of encrypted+compressed data) -> ChunkInfo.hash
     |
     v
  Upload as Telegram file message, replying to the file's metadata message
```

--------------------------------

### Televault Configuration Schema

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

Defines the structure for the main configuration file (`config.json`). Includes settings for channel ID, message IDs, chunk size, compression, encryption, parallelism, and low-resource mode parameters. These settings control Televault's operational behavior and resource utilization.

```json
{
  "channel_id": -1001234567890,
  "index_msg_id": 42,
  "snapshot_index_msg_id": 150,
  "chunk_size": 268435456,
  "compression": true,
  "encryption": true,
  "parallel_uploads": 8,
  "parallel_downloads": 10,
  "use_async_io": true,
  "low_resource_mode": false,
  "low_resource_chunk_size": 33554432,
  "low_resource_parallelism": 2,
  "low_resource_hash_workers": 1,
  "max_retries": 3,
  "retry_delay": 1.0
}
```

--------------------------------

### Televault Configuration File

Source: https://github.com/yahyatoubali/televault/blob/dev/README.md

This JSON object represents the configuration settings for Televault. It specifies parameters like channel ID, message IDs for indexing, chunk size, compression, encryption, and retry settings. Ensure this file is located at ~/.config/televault/config.json.

```json
{
  "channel_id": -1003652003243,
  "index_msg_id": 42,
  "snapshot_index_msg_id": 150,
  "chunk_size": 268435456,
  "compression": true,
  "encryption": true,
  "parallel_uploads": 8,
  "parallel_downloads": 10,
  "use_async_io": true,
  "low_resource_mode": false,
  "max_retries": 3,
  "retry_delay": 1.0
}
```

--------------------------------

### Televault CLI Command Structure

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

This section details the structure of Televault CLI commands for various operations like push, pull, list, and more. It includes common flags for each command.

```bash
tvt push <path>                    Upload file/directory
  --password / -p                  Encryption password
  --no-compress                    Disable compression
  --no-encrypt                     Disable encryption
  --recursive / -r                 Upload directory recursively
  --resume                         Resume interrupted upload
  --low-resource                   Enable low-resource mode (<2GB RAM)

tvt pull <file_id_or_name>         Download file
  --output / -o                    Output path (-o - for stdout)
  --password / -p                  Decryption password
  --resume                         Resume interrupted download
  --low-resource                   Enable low-resource mode (<2GB RAM)

tvt ls                             List files
  --json                           JSON output (pipeable)
  --sort <name|size|date>          Sort order

tvt cat <file_id_or_name>          Output file to stdout (pipeable)

tvt preview <file_id_or_name>      File preview without full download
  --password / -p                  Decryption password

tvt info <file_id_or_name>         Detailed file information
  --json                           JSON output

tvt stat                           Vault status/overview
  --json                           JSON output

tvt find <query>                   Search files by name
  --json                           JSON output

tvt rm <file_id_or_name>           Delete file
  --yes / -y                       Skip confirmation

tvt verify <file_id_or_name>       Verify file integrity
  --password / -p                  Decryption password

tvt gc                             Garbage collection (dry-run by default)
  --force                          Actually delete orphaned messages
  --clean-partials                 Remove incomplete uploads

tvt login                          Telegram authentication
  --phone / -p <number>            Phone number

tvt setup                          Configure storage channel
  --channel-id / -c <id>           Use existing channel by ID
  --auto / -a                      Auto-create channel without prompting

tvt channel                        Show current channel info

tvt mount <mount_point>            Mount as FUSE filesystem
  --password / -p                  Encryption password
  --read-only                      Read-only mount
  --cache-dir                      Local cache directory
  --cache-size                     Max cache size in MB (default 100)
  --allow-other                     Allow other users
  --foreground / --background      Foreground or daemon mode

tvt serve                          Start WebDAV server
  --host / -h <addr>               Bind address (default 0.0.0.0)
  --port / -p <port>               Port (default 8080)
  --password / -P                  Encryption password
  --read-only                      Read-only mode
  --cache-dir                      Local cache directory

tvt whoami                         Show current Telegram account
tvt logout                         Clear session
tvt tui                            Launch interactive TUI

tvt backup create <path>           Create backup snapshot
  --name / -n                      Snapshot name
  --password / -p                  Encryption password
  --incremental / -i               Incremental backup
  --dry-run                        Show plan without uploading

tvt backup restore <snapshot_id>   Restore from snapshot
  --output / -o                    Output directory
  --password / -p                  Decryption password
  --files / -f                     Specific files to restore

tvt backup list                    List snapshots
tvt backup delete <snapshot_id>     Delete snapshot
tvt backup prune                   Prune old snapshots
  --keep-daily / --keep-weekly / --keep-monthly
  --dry-run
tvt backup verify <snapshot_id>     Verify snapshot integrity

tvt schedule create <path>          Create backup schedule
  --name / -n, --interval, --password, --incremental

tvt schedule list / run / delete / install / uninstall / show-systemd

tvt watch                          Watch directories for changes
  --path / -p, --interval, --exclude
```

--------------------------------

### scrypt Key Derivation Parameters

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

Specifies the parameters used for scrypt key derivation to generate a 32-byte AES key from a password and salt.

```plaintext
scrypt(password, salt):
  N = 2^17 (131072)
  r = 8
  p = 1
  output length = 32 bytes (256-bit AES key)
```

--------------------------------

### Watch Directory for Changes

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/commands.md

Monitor a directory for file changes. You can set a polling interval and exclude specific patterns.

```bash
tvt watch --path <dir>
```

```bash
tvt watch --interval 10
```

```bash
tvt watch --exclude "*.tmp"
```

--------------------------------

### Development Workflow Branching

Source: https://github.com/yahyatoubali/televault/blob/dev/CONTRIBUTING.md

Steps to create a new feature branch for development, ensuring it's based on the 'dev' branch.

```bash
git checkout dev
git pull origin dev
git checkout -b feature/my-feature
```

--------------------------------

### Resumable Download Progress File Structure

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/security.md

Shows the JSON structure of the progress file used for resumable downloads. It includes file identification, completed chunk information, total chunks, and a CRC32 checksum for integrity.

```json
{
  "file_id": "abc123",
  "completed_chunks": [0, 1, 2],
  "total_chunks": 5,
  "checksum": "a1b2c3d4"
}
```

--------------------------------

### AES-256-GCM Chunk Encryption Structure

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/security.md

Illustrates the on-disk structure of an encrypted chunk, including the salt, nonce, ciphertext, and authentication tag.

```plaintext
[16-byte salt][12-byte nonce][ciphertext...][16-byte auth tag]
```

--------------------------------

### Handling AuthKeyError/Unauthorized

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

This error indicates that the session has expired. Re-authenticate by running `tvt login`.

```python
AuthKeyError/Unauthorized
```

--------------------------------

### Download Decryption Pipeline

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

Details the process of downloading and decrypting file chunks. Includes hash verification and optional decompression.

```plaintext
Download chunk message by message_id
     |
     v
  Verify hash (BLAKE3 of raw data matches ChunkInfo.hash)
     |
     v
  Decryption (AES-256-GCM)
  -- extract 28-byte header (salt + nonce)
  -- scrypt(password, salt) -> key
  -- decrypt and verify GCM tag
     |
     v
  Optional Decompression (zstd)
     |
     v
  Verify original_hash (BLAKE3 matches ChunkInfo.original_hash)
  -- catches wrong-password decryption that passes GCM
     |
     v
  Write chunk at correct offset via ChunkWriter
     |
     v
  After all chunks: verify file-level BLAKE3 hash matches FileMetadata.hash
```

--------------------------------

### Stream File Content with TeleVault

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/index.md

Stream the content of a file from TeleVault to standard output, allowing it to be piped to other commands. You can also push standard input to TeleVault.

```bash
# Stream to stdout
tvt cat config.yaml | grep api_key
cat secret.txt | tvt push - --name secret.txt
```

--------------------------------

### Mount TeleVault as a read-only filesystem

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/virtualization.md

Mount your TeleVault vault as a read-only filesystem. This is useful for safely accessing encrypted files without the risk of accidental modification.

```bash
# Read-only mount
tvt mount ~/vault --read-only
```

--------------------------------

### Mount TeleVault with custom cache settings

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/virtualization.md

Mount your TeleVault vault with read-write access and configure custom cache settings. This allows for faster access to frequently used data by specifying the cache size and directory.

```bash
# Read-write with custom cache
tvt mount ~/vault --cache-size 500 --cache-dir /tmp/tvcache
```

--------------------------------

### Handling RuntimeError (Not connected)

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

This error occurs when trying to perform an operation without being logged in. Run `tvt login` first.

```python
RuntimeError("Not connected")
```

--------------------------------

### Televault Low-Resource Mode

Source: https://github.com/yahyatoubali/televault/blob/dev/README.md

Utilize low-resource mode for machines with limited RAM or CPU (<2 GB RAM) to reduce memory footprint during file operations.

```bash
tvt push bigfile.zip --low-resource
tvt pull bigfile.zip --low-resource
```

--------------------------------

### Monitor Transfer Speed

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/hardware.md

The CLI displays real-time transfer speeds using Exponential Moving Average (EMA) smoothing. This provides an accurate representation of network performance, updated per chunk.

```text
⬆️ Uploading photo.jpg (3/8 chunks)  45.2 MB/s  ████████████░░░░░░░░ 65%
```

--------------------------------

### Writing file content to stdout with tvt cat

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

Use this command to display the content of a file to standard output.

```bash
tvt cat <file>
```

--------------------------------

### Televault Download Decryption Pipeline

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/engine.md

Details the process of downloading and decrypting a file, including verification steps.

```text
Download chunk by message_id
      │
      ▼
   Verify BLAKE3 hash (ChunkInfo.hash)
      │
      ▼
   AES-256-GCM Decryption
   ── extract 28-byte header (salt + nonce)
   ── scrypt(password, salt) → key
   ── decrypt and verify GCM tag
      │
      ▼
   zstd Decompression
      │
      ▼
   Verify original_hash (BLAKE3)
   ── catches wrong-password decryption that passes GCM
      │
      ▼
   Write chunk at offset via ChunkWriter
      │
      ▼
   Verify file-level BLAKE3 hash (FileMetadata.hash)
```

--------------------------------

### FileMetadata Storage Model

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/engine.md

Details the metadata for a single file, including its chunks, encryption status, and timestamps.

```json
{
  "id": "abc123def456",
  "name": "photo.jpg",
  "size": 5242880,
  "hash": "a1b2c3d4...64 chars BLAKE3",
  "chunks": [
    {
      "index": 0,
      "message_id": 43,
      "size": 10485780,
      "hash": "e5f6a7b8...post-processing",
      "original_hash": "c9d0e1f2...pre-processing"
    }
  ],
  "encrypted": true,
  "compressed": true,
  "created_at": 1700000000.0
}
```

--------------------------------

### Writing to stdout with tvt pull

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

Use this command to pull data from Televault and write it to standard output.

```bash
tvt pull -o -
```

--------------------------------

### Incompressible File Extensions

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

Lists file extensions for which compression is skipped during the upload process.

```plaintext
Images: .jpg .jpeg .png .gif .webp .heic .heif .avif
Video: .mp4 .mkv .avi .mov .webm .m4v .wmv .flv
Audio: .mp3 .aac .ogg .opus .flac .m4a .wma
Archives: .zip .gz .bz2 .xz .7z .rar .zst .lz4 .lzma
Documents: .pdf .docx .xlsx .pptx .odt
Other: .woff .woff2 .br
```

--------------------------------

### Resume Interrupted Operations

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/hardware.md

Televault supports resuming interrupted uploads and downloads. Use the --resume flag to continue operations from where they left off, preserving partial data.

```bash
# Resume interrupted upload
tvt push large_file.iso --resume

# Resume interrupted download
tvt pull large_file.iso --resume
```

--------------------------------

### Handling ConnectionError

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

This error indicates a problem with the internet connection. Ensure you are connected to the internet.

```python
ConnectionError
```

--------------------------------

### Integrity Verification Flow

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/security.md

Explains how TeleVault uses BLAKE3 hashes to verify data integrity at different stages of the encryption and decryption process. The original hash verification after decryption is crucial for detecting incorrect password usage.

```plaintext
decrypt → decompress → verify original_hash → FAIL → wrong password
```

--------------------------------

### Exponential Backoff Calculation

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

Calculates the delay for retries using an exponential backoff strategy with jitter. Defaults are provided for max retries, base delay, and maximum delay.

```python
delay = min(base_delay * 2^attempt, max_delay)
delay = delay * (0.5 + random())   # jitter
```

--------------------------------

### Stream to Stdout

Source: https://github.com/yahyatoubali/televault/blob/dev/docs/commands.md

Redirects the output of `tvt cat` to standard output, enabling further processing with other command-line tools like `grep`.

```bash
tvt cat config.yaml | grep api_key
```

--------------------------------

### Handling FloodWaitError

Source: https://github.com/yahyatoubali/televault/blob/dev/ARCHITECTURE.md

This error suggests that too many requests have been made in a short period. Wait a few minutes before retrying.

```python
FloodWaitError
```