CLI Reference

Sietch is a secure, decentralized file system designed for operation in harsh, disconnected environments. It allows users to securely synchronize encrypted data across machines, even with limited connectivity. This reference documents all available commands, their options, and practical examples.

Global Flags

These flags are available for all sietch commands:

  • -v, --verbose - Enable verbose output
  • -h, --help - Show help for any command

Core Commands Overview

Vault Management

  • init - Initialize a new Sietch vault
  • scaffold - Scaffold a vault from templates

File Operations

  • add - Add files to your vault
  • get - Retrieve files from your vault
  • delete - Delete files from your vault
  • ls - List files in your vault

Sync & Discovery

  • sync - Synchronize with another vault
  • discover - Discover peers on local network
  • sneak - Transfer data via sneakernet (USB, physical media)

Maintenance

  • dedup - Manage deduplication and storage optimization
  • completion - Generate shell autocompletion

Vault Management

sietch init

Initialize a new Sietch vault with secure encryption and configurable options. This creates the necessary directory structure and configuration files for your vault.

Bash
$sietch init --name desert-cache --key-type aes --passphrase
Click to copy

Key Options:

OptionTypeDefaultDescription
--namestringmy-sietchName of the vault
--pathstring.Path to create the vault
--key-typestringaesEncryption type: aes, gpg, or none
--passphraseflag-Protect key with passphrase
--passphrase-valuestring-Passphrase value (NOT RECOMMENDED)
--key-filestring-Path to existing key file

Encryption & Security:

OptionTypeDefaultDescription
--aes-modestringgcmAES encryption mode (gcm, cbc)
--use-scryptflag-Use scrypt for key derivation
--scrypt-nint32768scrypt N parameter
--scrypt-rint8scrypt r parameter
--scrypt-pint1scrypt p parameter
--rsa-bitsint4096RSA key size (min 2048)

Storage Configuration:

OptionTypeDefaultDescription
--chunking-strategystringfixedChunking strategy: fixed or cdc
--chunk-sizestring4MBSize of chunks
--compressionstringnoneCompression: none, gzip, or zstd
--hashstringsha256Hash algorithm: sha256 or blake3

Deduplication:

OptionTypeDefaultDescription
--enable-dedupflagtrueEnable deduplication
--dedup-strategystringcontentDeduplication strategy
--dedup-min-sizestring1KBMinimum chunk size for dedup
--dedup-max-sizestring64MBMaximum chunk size for dedup
--dedup-gc-thresholdint1000Unreferenced chunks before GC suggestion

Other Options:

OptionTypeDefaultDescription
--interactiveflag-Use interactive mode
--from-configstring-Initialize from config file
--templatestring-Use predefined template
--forceflag-Force re-initialization
--authorstring-Author metadata
--tagsstrings-Tags for vault
--sync-modestringmanualSync mode: manual or auto

Examples:

Basic Setup
# Quickstart vault with defaults
sietch init

# Named vault with AES encryption
sietch init --name "desert-cache" --key-type aes --passphrase
Advanced Configuration
# Custom chunking and GPG encryption
sietch init --name research-vault \
  --chunking-strategy cdc \
  --chunk-size 2MB \
  --key-type gpg

# AES with custom scrypt parameters
sietch init --key-type aes --passphrase \
  --use-scrypt --scrypt-n 32768 \
  --scrypt-r 8 --scrypt-p 1
Template & Configuration
# Use config file from template or backup
sietch init --from-config my-old-vault.yaml

# Use predefined template
sietch init --template photo-vault

# Interactive mode
sietch init --interactive

sietch scaffold

Scaffold a new Sietch vault using predefined templates optimized for specific use cases.

Options:

OptionTypeDefaultDescription
--templatestring-Template to use (required)
--namestring-Name for the vault
--pathstring-Path where to create the vault
--forceflag-Force creation even if directory exists
--listflag-List available templates

Available Templates:

  • photoVault - Optimized for photo storage with high compression and smart deduplication
  • reporterVault - Optimized for journalism and document management with secure storage

Examples:

List Templates
# List available templates
sietch scaffold --list
Create from Template
# Create photo vault
sietch scaffold --template photoVault --name "My Photos"

# Create reporter vault with custom path
sietch scaffold --template reporterVault \
  --name "Investigation Files" \
  --path /secure/reports

File Operations

sietch add

Add a file from your local filesystem to your Sietch vault.

Bash
$sietch add document.txt vault/documents/
Click to copy

Usage:

sietch add <source_path> <destination_path> [flags]

Options:

OptionTypeDescription
--forceflagForce add without confirmation
--tagsstringComma-separated tags for the file
--passphrase-valuestringPassphrase for encrypted vault

Examples:

Basic Add
# Add a document
sietch add document.txt vault/documents/

# Add with tags
sietch add report.pdf vault/reports/ --tags "urgent,quarterly"
Batch Operations
# Add entire directory
sietch add ~/photos/ vault/photos/

# Force add without confirmation
sietch add large-file.zip vault/archives/ --force

sietch get

Retrieve a file from your Sietch vault and save it to your local filesystem.

Bash
$sietch get vault/documents/report.pdf ~/Downloads/
Click to copy

Usage:

sietch get <file_path> <destination_path> [flags]

Options:

OptionTypeDescription
--forceflagForce overwrite if file exists
--skip-decryptionflagRetrieve raw chunks (for recovery)

Examples:

Basic Retrieval
# Get a specific file
sietch get document.txt ~/Documents/

# Get from subdirectory
sietch get vault/photos/vacation.jpg ./retrieved_photos/
Advanced Options
# Force overwrite existing file
sietch get report.pdf ~/Downloads/ --force

# Get raw chunks for recovery
sietch get corrupted-file.dat ./recovery/ --skip-decryption

sietch ls

List files stored in your Sietch vault with various display options.

Bash
$sietch ls --long --tags
Click to copy

Usage:

sietch ls [path] [flags]

Options:

OptionTypeDefaultDescription
--longflag-Use long listing format
--tagsflag-Show file tags
--sortstringpathSort by: name, size, time, path

Examples:

Basic Listing
# List all files
sietch ls

# List files in specific directory
sietch ls docs/
Detailed Views
# Long format with details
sietch ls --long

# Show tags and sort by size
sietch ls --tags --sort=size

# Sort by modification time
sietch ls --sort=time

sietch delete

Delete a file from your Sietch vault and optionally clean up associated chunks.

Bash
$sietch delete docs/old-report.pdf
Click to copy

Usage:

sietch delete <file_path> [flags]

Options:

OptionTypeDescription
--forceflagForce deletion without confirmation
--keep-chunksflagKeep chunks, only delete manifest

Examples:

Basic Deletion
# Delete a specific file
sietch delete docs/report.pdf

# Force delete without confirmation
sietch delete notes.txt --force
Advanced Options
# Delete manifest but keep chunks (for recovery)
sietch delete photo.jpg --keep-chunks

Sync & Discovery

sietch sync

Synchronize files with another Sietch vault over the network using libp2p.

Bash
$sietch sync
Click to copy

Usage:

sietch sync [peer-address] [flags]

Options:

OptionTypeDefaultDescription
--portint-Port for libp2p (0 for random)
--timeoutint60Discovery timeout in seconds
--read-onlyflag-Only receive files, don't send
--force-trustflag-Auto-trust new peers

Examples:

Auto-Discovery
# Auto-discover and sync with local peers
sietch sync

# Sync with custom timeout
sietch sync --timeout 30
Direct Connection
# Sync with specific peer
sietch sync /ip4/192.168.1.5/tcp/4001/p2p/QmPeerID

# Read-only sync (receive only)
sietch sync --read-only

sietch discover

Discover other Sietch vaults on your local network using mDNS.

Bash
$sietch discover --continuous
Click to copy

Options:

OptionTypeDefaultDescription
--timeoutint60Discovery timeout in seconds
--continuousflag-Run until interrupted
--portint-Port for libp2p node
--vault-pathstring.Path to vault directory

Examples:

Basic Discovery
# Run discovery with default settings
sietch discover

# Custom timeout
sietch discover --timeout 30
Continuous Discovery
# Run continuously until interrupted
sietch discover --continuous

# Use specific port
sietch discover --port 9001

sietch sneak

Transfer files and chunks from another vault via sneakernet (USB drives, external media).

Bash
$sietch sneak --source /media/usb/vault
Click to copy

Options:

OptionTypeDefaultDescription
--sourcestring-Source vault path
--deststringcurrentDestination vault path
--interactiveflagtrueInteractive vault selection
--dry-runflag-Show what would be transferred
--filesstrings-Specific file patterns to transfer
--excludestrings-File patterns to exclude
--auto-resolveflag-Auto-resolve conflicts by renaming

Examples:

Interactive Mode
# Interactive discovery and selection
sietch sneak

# Dry run to see what would transfer
sietch sneak --source /media/usb/vault --dry-run
Targeted Transfer
# Transfer from specific vault
sietch sneak --source /media/usb/research-vault

# Transfer specific file patterns
sietch sneak --files "*.pdf,docs/*" --source /usb/vault

# Exclude certain patterns
sietch sneak --source /backup/vault --exclude "*.tmp,temp/*"

Maintenance

sietch dedup

Manage deduplication settings and operations in your Sietch vault.

Bash
$sietch dedup stats
Click to copy

Subcommands:

  • stats - Show deduplication statistics
  • gc - Run garbage collection on unreferenced chunks
  • optimize - Optimize vault storage

Examples:

Statistics
# Show deduplication stats
sietch dedup stats
Maintenance
# Run garbage collection
sietch dedup gc

# Optimize storage
sietch dedup optimize

sietch completion

Generate autocompletion scripts for your shell.

Supported Shells:

  • bash - Bash completion
  • fish - Fish completion
  • zsh - Zsh completion
  • powershell - PowerShell completion

Examples:

Install Completion
# Generate bash completion
sietch completion bash > /etc/bash_completion.d/sietch

# Generate fish completion
sietch completion fish > ~/.config/fish/completions/sietch.fish

# Generate zsh completion
sietch completion zsh > ~/.config/zsh/completions/_sietch
Edit this page on GitHub
Table of Contents