Command-line reference

Every savorum command in one place, for running, maintaining, and backing up your server. Run savorum --help for the full summary, or savorum COMMAND --help for one command. If you built from source, use ./bin/savorum in place of savorum.

Command	Purpose
serve	Run the HTTP server and web interface
user	Create the first administrator, add an account, or reset a password
healthcheck	Probe a health URL, defaulting to local /api/v1/health
storage	Emit a JSON storage and backup-capacity inventory
check-database	Run SQLite integrity and foreign-key checks
checkpoint	Run and report a SQLite checkpoint
rebuild-search	Regenerate the disposable search index
scrub-assets	Report asset-store integrity problems
gc-assets	Collect unreferenced assets after a grace period
backup, verify, restore	Create, inspect, and restore a complete instance backup
export	Write portable SREF artifacts
import	Import SREF or supported third-party files
admin	The maintenance and backup commands above, grouped in one place
hosting	Operator commands for a managed instance
completion	Write a shell completion script

Output and exit codes

A command writes its result, such as a report, a user ID, or an exported file, to standard output. Prompts, confirmations, and errors go to standard error, so you can redirect the result safely. Add --quiet to any command to drop confirmations and never prompt; results and errors still appear.

Exit code	Meaning
0	Success, including --help
1	The command ran and the operation failed
2	The command line was wrong: unknown command or flag, or a missing option
130	The command was interrupted

Shell completion

savorum completion bash, fish, powershell, or zsh writes a completion script for that shell. For example, in bash:

source <(savorum completion bash)

Server

savorum serve --database PATH [flags]

Configure an instance lists the flags, their environment equivalents, and precedence.

Accounts

savorum user create-admin --database PATH [--login NAME] [--password-file FILE]
savorum user create --database PATH --actor ADMIN-USER-ID [--login NAME] [--password-file FILE]
savorum user reset-password --database PATH --user-id USER-ID [--password-file FILE]

These commands work on the database directly, with the server owner’s authority. With a terminal, they ask for the login name, then twice for a password without showing it. Without one, pass --login and --password-file; --password-file - reads standard input. There’s no password argument or password environment variable, so passwords stay out of shell history and process lists.

user create-admin creates the first administrator, who takes over the existing library. user reset-password takes --user-id, not a login name, and signs that user out everywhere. Each prints the account’s user ID, never the password. See Accounts and access.

Recovery and maintenance

savorum storage --database PATH [--assets DIRECTORY] [--backup-directory DIRECTORY]
savorum check-database --database PATH [--assets DIRECTORY]
savorum rebuild-search --database PATH [--assets DIRECTORY]
savorum checkpoint --database PATH [--assets DIRECTORY]
savorum scrub-assets --database PATH [--assets DIRECTORY]
savorum gc-assets --database PATH [--assets DIRECTORY] [--grace DURATION]
savorum backup --database PATH [--assets DIRECTORY] --output ARCHIVE
savorum verify --input ARCHIVE
savorum restore --input ARCHIVE --database PATH [--assets DIRECTORY]

savorum admin offers the same backup, verify, restore, storage, and database maintenance commands, with the same flags. It also has admin compatibility, which reports the database and backup formats this binary understands, and admin migrate, which applies database upgrades to a stopped instance. Its other subcommands are for hosting operators.

Managed-host operator commands

hosting commands are for a managed hosting service, or for an owner moving from Savorum Cloud. You don’t need them for ordinary self-hosting. Run savorum hosting --help for the current subcommands and flags.

Portable exchange

savorum export recipe --database PATH [--assets DIRECTORY] [--output FILE] [--revision N] ENTRY-ID
savorum export recipes --database PATH [--assets DIRECTORY] [--output FILE] ENTRY-ID...
savorum export book --database PATH [--assets DIRECTORY] [--output FILE] BOOK-ID
savorum export library --database PATH [--assets DIRECTORY] --output DIRECTORY
savorum import --database PATH [--assets DIRECTORY] --input FILE-OR-DIRECTORY
               [--on-duplicate reject|skip|replace]

These commands work on the database directly, with the server owner’s authority.

Import

--input takes a file or a folder. For a folder, Savorum reads the supported files directly inside it, not in subfolders, and saves the whole batch or nothing. It accepts SREF recipes and packages and recognized third-party export files.

By default, importing a recipe that is already in the library fails. Add --on-duplicate skip to keep the existing recipe, or --on-duplicate replace to replace it.

One import reads at most 500 files and 500 recipes, 64 MiB per file, and 256 MiB in total. For a large export you trust, raise the size limits with --max-file-bytes and --max-input-bytes, in bytes:

savorum import --database /var/lib/savorum/savorum.db --input ./recipes \
  --max-input-bytes 536870912

Export

ENTRY-ID is the recipe’s ID in your library, as shown in the app or the API. It is not the recipe’s SREF ID. --output - writes a recipe, selection, or book to standard output.

Exports hold recipes and their photos. Tags, books, ratings, personal notes, and cooking history stay behind; a backup keeps everything. An export fails if a recipe has no ingredients or steps, or if a photo file is missing from the asset folder. Savorum never downloads a missing photo again.

Next: Build on Savorum with the HTTP API. Or see Import recipes and Export recipes in the browser.