Server CLI Reference

The stowry binary provides commands for running and managing the Stowry server.

Global Flags

These flags are available for all commands:

--config, -c string     Config file paths (can be specified multiple times, merged left-to-right)
--db-type string        Database type (sqlite, postgres)
--db-dsn string         Database connection string
--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

add

Import files from external paths into stowry storage.

stowry add [flags] <file1> [file2] ...

Flags:

Flag	Type	Default	Description
`--dest`, `-d`	string		Destination path prefix in storage
`--recursive`, `-r`	bool	false	Recursively add directories
`--no-clobber`, `-n`	bool	false	Skip existing files instead of overwriting
`--quiet`, `-q`	bool	false	Suppress per-file output

Examples:

# Add a single file
stowry add /path/to/file.txt

# Add with a destination prefix
stowry add --dest images/ /path/to/photo.jpg

# Add a directory recursively
stowry add -r /path/to/assets

# Add files to a specific prefix without overwriting existing
stowry add --dest uploads/ --no-clobber /path/to/file.txt

# Quiet mode for scripting
stowry add -q -r /path/to/assets

Behavior:

Copies files from the source path to the storage directory
Registers metadata in the database (path, content type, hash, size)
Content type is detected from file extension
Existing files are overwritten by default (use --no-clobber to skip)
For directories, requires --recursive flag

Output:

INFO added path=photo.jpg content_type=image/jpeg
INFO add complete added=5 skipped=2

remove

Soft-delete files from stowry storage.

stowry remove [flags] <path1> [path2] ...

Flags:

Flag	Type	Default	Description
`--prefix`, `-p`	bool	false	Treat paths as prefixes and remove all matching files
`--quiet`, `-q`	bool	false	Suppress per-file output

Examples:

# Remove a single file
stowry remove myfile.txt

# Remove multiple files
stowry remove file1.txt file2.txt file3.txt

# Remove all files with a prefix (e.g., a directory)
stowry remove --prefix images/

# Quiet mode for scripting
stowry remove -q file.txt

Behavior:

Marks files as deleted by setting deleted_at timestamp in metadata
Physical files remain on disk until stowry cleanup runs
Deleted files are no longer accessible via the API
With --prefix, removes all files matching the prefix (paginated internally)
Non-existent paths are logged as warnings, not errors

Output:

INFO removed path=myfile.txt
INFO remove complete removed=3 not_found=1

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:

Scans the storage directory recursively
For each file found:
- Calculates SHA256 hash (used as ETag)
- Detects content type from file extension
- Creates or updates metadata entry
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:

Queries metadata for soft-deleted files (where deleted_at is set but cleaned_up_at is not)
For each file:
- Deletes the physical file from storage
- Sets cleaned_up_at timestamp in metadata
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