Server CLI: serve, migrate, validate, populate

Server CLI Reference

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

Global Flags

Every configuration setting is reachable three ways, highest first: a flag, an environment variable, then the config files. stowry <command> --help lists each flag alongside the variable that reaches the same setting.

The ones used most often:

Flag	Environment variable	Default	Description
`-c`, `--config`	`STOWRY_CONFIG`	`./config.yaml`	Config files, merged left to right
`--db-type`	`STOWRY_DATABASE_TYPE`	`sqlite`	Database type
`-d`, `--db-dsn`	`STOWRY_DATABASE_DSN`	`:memory:`	Database connection string
`-s`, `--storage-path`	`STOWRY_STORAGE_PATH`	`:memory:`	Storage directory
`-a`, `--access-key`	`STOWRY_ACCESS_KEY`	-	Access key for signed requests
`-k`, `--secret-key`	`STOWRY_SECRET_KEY`	-	Secret key for signed requests

Both stores default to :memory:, so with no configuration the server keeps nothing once it exits.

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`)
`-m`, `--migrate`	bool	false	Create the metadata schema before serving
`-p`, `--populate`	bool	false	Record the files already in the storage directory before serving

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, owner-only
Migrates an in-memory database, since nothing else could have. A database on disk is migrated only with --migrate, or by running stowry migrate first
Rejects auth.read: private in static and spa modes at startup, because a browser cannot sign a request
Gracefully shuts down on SIGINT or SIGTERM
Default read timeout: 30 seconds
Default write timeout: 30 seconds
Default idle timeout: 120 seconds

migrate

Create the tables and indexes stowry needs, then confirm the result.

stowry migrate [flags]

Run this before serving from a database on disk: serve migrates an in-memory database only.

Flags:

Flag	Type	Default	Description
`-p`, `--populate`	bool	false	Record the files already in the storage directory once the schema is in place

Examples:

# Create the schema
stowry migrate --db-dsn stowry.db

# Create it and record an existing directory of files in one go
stowry migrate --db-dsn stowry.db --storage-path ./data --populate

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

Behavior:

Idempotent: running it twice changes nothing
Never alters a table that already exists. A table stowry did not build is reported rather than changed, so migrating onto an older or foreign schema fails instead of half-working
Warns when the database is in memory, since nothing it creates will outlive the process

validate

Report whether the existing schema is the one stowry expects.

stowry validate

Nothing is created or altered, so this is what a deployment that migrates out of band runs in place of migrate. It exits non-zero when the schema is missing or wrong.

It checks the metadata table’s columns, their types and nullability, and the unique constraint on path that every write depends on.

Examples:

stowry validate --db-dsn stowry.db
stowry validate --db-type postgres --db-dsn "postgres://localhost/stowry"

populate

Record metadata for the files already in the storage directory, so a directory of existing files can be served without uploading anything.

stowry populate [flags]

The files are read, never written: their layout under the storage path becomes the object paths.

Flags:

Flag	Type	Default	Description
`-m`, `--migrate`	bool	false	Create the metadata schema first

Examples:

# Record an existing directory
stowry populate --db-dsn stowry.db --storage-path ./data

# Create the schema and record in one go
stowry populate --db-dsn stowry.db --storage-path ./data --migrate

# Pick up whatever changed on disk
stowry populate --db-dsn stowry.db --storage-path ./data

Behavior:

Repeatable: an entry that already exists is updated in place, picking up whatever changed on disk
The schema must already exist unless --migrate is passed
A file whose path the server could not serve stops the run, and the entries recorded before it are kept
This is how content reaches a static or spa server, which route no writes

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 connected to database type=sqlite
INFO starting server addr=:5708