CLI Reference

CLI Reference

Stowry provides a command-line interface for managing the server and performing administrative tasks.

Global Flags

These flags are available for all commands:

--config string         Config file path (default "config.yaml")
--db-type string        Database type (sqlite, postgres)
--db-dsn string         Database connection string
--db-table string       Database table name
--storage-path string   Storage directory path
-h, --help              Help for the command

Commands

serve

Start the HTTP server.

stowry serve [flags]

Flags:

Flag	Type	Default	Description
--port	int	5708	HTTP server port
--mode	string	store	Server mode (store, static, spa)

Examples:

# Start with defaults
stowry serve

# Custom port
stowry serve --port 8080

# Static file server mode
stowry serve --mode static

# SPA mode with custom config
stowry serve --mode spa --config /etc/stowry/config.yaml

# Override database via environment
STOWRY_DATABASE_TYPE=postgres \
STOWRY_DATABASE_DSN="postgres://localhost/stowry" \
stowry serve

Behavior:

• Creates the storage directory if it doesn’t exist
• Runs database migrations automatically
• Gracefully shuts down on SIGINT or SIGTERM
• Default read timeout: 30 seconds
• Default write timeout: 30 seconds
• Default idle timeout: 120 seconds

---

init

Initialize the metadata database from existing storage files.

stowry init [flags]

Use Cases:

• Setting up Stowry with pre-existing files
• Recovering metadata after database loss or corruption
• Migrating from another storage system

Examples:

# Initialize from default storage path
stowry init

# With custom paths
stowry init --storage-path /var/data --db-dsn /var/lib/stowry/metadata.db

# With PostgreSQL
stowry init --db-type postgres --db-dsn "postgres://localhost/stowry"

Behavior:

1. Scans the storage directory recursively
2. For each file found:
   • Calculates SHA256 hash (used as ETag)
   • Detects content type from file extension
   • Creates or updates metadata entry
3. Reports total files indexed

Output:

INFO scanning storage directory path=./data
INFO initialization complete files_indexed=42

---

cleanup

Permanently remove soft-deleted files from storage.

stowry cleanup [flags]

Flags:

Flag	Type	Default	Description
--limit	int	100	Maximum files to clean up per batch

Examples:

# Clean up with default limit
stowry cleanup

# Clean up more files
stowry cleanup --limit 500

# Clean up with custom config
stowry cleanup --config /etc/stowry/config.yaml --limit 1000

Behavior:

1. Queries metadata for soft-deleted files (where deleted_at is set but cleaned_up_at is not)
2. For each file:
   • Deletes the physical file from storage
   • Sets cleaned_up_at timestamp in metadata
3. Reports total files cleaned

Output:

INFO starting cleanup limit=100
INFO cleanup complete files_cleaned=15

Scheduling:

Run cleanup periodically to reclaim storage space:

# Cron job (every hour)
0 * * * * /usr/local/bin/stowry cleanup --config /etc/stowry/config.yaml

# Systemd timer
[Timer]
OnCalendar=hourly
Persistent=true

---

help

Display help for any command.

stowry help [command]
stowry [command] --help

Examples:

stowry help
stowry help serve
stowry serve --help

---

completion

Generate shell autocompletion scripts.

stowry completion [bash|zsh|fish|powershell]

Examples:

# Bash
stowry completion bash > /etc/bash_completion.d/stowry

# Zsh
stowry completion zsh > "${fpath[1]}/_stowry"

# Fish
stowry completion fish > ~/.config/fish/completions/stowry.fish

Exit Codes

Code	Meaning
0	Success
1	General error

Logging

Stowry logs to stdout using structured logging (slog). Control verbosity with the log.level configuration option or STOWRY_LOG_LEVEL environment variable.

# Debug logging
STOWRY_LOG_LEVEL=debug stowry serve

# Quiet mode (errors only)
STOWRY_LOG_LEVEL=error stowry serve

Log format:

INFO starting server addr=:5708 mode=store
INFO connected to sqlite dsn=stowry.db