This page is generated from the binary, not written beside it. Everything below came out of sloop <command> --help at build time, so a flag cannot appear here unless the CLI prints it, and cannot be missing if it does. Built from sloop 0.1.5.
That makes --help the authority and this a convenience — a faster way to read all of it at once, and something a search engine can index. If the two ever disagree, the binary in front of you is right and the page is stale.
The global flags
These eleven work on every command, and they are not repeated in the tables further down — each command's table lists only what is its own. They are the ones every command has, worked out by intersection rather than kept in a list, so a flag that stopped being global would leave this section on its own.
| Flag | What it does |
|---|---|
--global | Use the global registry, whichever directory you are standing in |
-C, --project <PATH|NAME> | Work on this project: a directory, or a name sloop init recorded |
--password-command <COMMAND> | Take the password from this command's output instead of wherever the registry says |
-y, --yes | Answer yes to a question this would otherwise stop and ask |
--force | Override a refusal that is there to protect something |
--confirm <NAME> | The name of the thing being destroyed, typed out |
-q, --quiet | Say nothing but what went wrong |
--json | Print one JSON document instead of talking |
--no-color | Never colour the output, whatever this terminal supports |
--log-file <PATH> | Append everything this run prints to a file as well |
--dry-run | Say what would happen and change nothing |
Why --yes, --force and --confirm are three things
They look interchangeable and are not, and reaching for the wrong one is how an automated run either stops when it should not have or destroys something it should not have.
--yesanswers a question. A command that would stop and ask something proceeds. It is never enough to destroy a named thing, and it is never a way past a refusal.--forceoverrides a refusal. A refusal is sloop declining to do something because of what it found — a circular foreign key, a source that is also the destination. It answers no questions, and the refusal that can be overridden says so when it fires.--confirm <NAME>types the name out. It is the only way to run a destructive command with no terminal, and it has to match exactly — so a scheduled line names the thing it destroys and cannot be repointed at something else by editing one flag.
With no terminal to ask at, sloop never prompts. It exits 2 and names the exact flag that would have answered the question, which is why a scheduled run can fail but cannot hang. Automation has the exit codes and the rest of it.
Getting set up
Preparing a machine, and a project registry in a directory.
sloop setup
Prepare the PostgreSQL 18 sloop keeps its own state in.
Runs on a machine that has not been set up, and is safe to run again on one that has. A PostgreSQL 18 already serving on 5432 is used as it stands; anything else gets a cluster of sloop's own on 5433, which disturbs nothing already on the machine.
| Flag | What it does |
|---|---|
--superuser-password-command <COMMAND> | A command that prints the superuser password of the PostgreSQL already on this machine, for a run with no terminal to ask at |
--superuser-password-stdin | Read that password from standard input instead of asking for it |
--db-password-command <COMMAND> | A command that prints the password to give sloop's own database user |
--db-password-stdin | Read that password from standard input instead of generating one |
sloop init
Start a project registry in this directory, or in the one -C names
Takes no flags of its own — only the 11 global ones above.
Databases
Telling sloop about a database, and changing or forgetting what it knows.
sloop db
Tell sloop about a database, and change or forget what it knows
Subcommands: add, create, list, test, edit, rename, remove, drop. Each has its own entry below.
Takes no flags of its own — only the 11 global ones above.
sloop db add
Register a database, by URL or field by field
| Argument | What it is |
|---|---|
<NAME> | What to call it here. Not the database's own name — the label you will type |
| Flag | What it does |
|---|---|
--url <URL> | The whole connection in one string: postgres://app@db:5432/orders |
--engine <ENGINE> | postgres, mysql or mariadb |
--host <HOST> | Host name or address |
--port <PORT> | Port. Defaults to the engine's own |
--database <NAME> | The database's name on the server |
--user <ROLE> | The role to connect as |
--keyring | Keep the password in the OS keyring. The default |
--encrypted-file | Keep it in the Argon2id-encrypted file, for a machine with no keyring |
--env <VARIABLE> | Read it from this environment variable at run time, for automation |
--password-from <COMMAND> | Run this and read the password from its output, for a team password manager |
--password-stdin | Take the password from standard input instead of asking for it |
--test | Connect before saving, and refuse to save if it does not work |
--ssh-host <HOST> | Reach this database through an SSH server, because its own port is not open |
--ssh-port <PORT> | The SSH server's port. 22 when left out. Not the database's port |
--ssh-user <USER> | Who to be on the SSH server. ~/.ssh/config, then your own username, when left out |
--ssh-identity <PATH> | A particular private key, as ssh -i takes it |
--no-ssh | Stop going through an SSH server. The connection becomes a direct one |
--ssh-keyring | Keep the key's passphrase in the OS keyring |
--ssh-encrypted-file | Keep it in the Argon2id-encrypted store, for a machine with no keyring |
--ssh-env <VARIABLE> | Read it from this environment variable at run time, for automation |
--ssh-passphrase-from <COMMAND> | Run this and read the passphrase from its output, for a team password manager |
--ssh-passphrase-stdin | Take the passphrase from standard input instead of asking for it |
sloop db create
Create a database and the role that owns it, then register it
| Argument | What it is |
|---|---|
<NAME> | What to call it here. The label you will type from now on |
| Flag | What it does |
|---|---|
--engine <ENGINE> | Which engine: postgres, mysql or mariadb |
--host <HOST> | The server it goes on [default: 127.0.0.1] |
--port <PORT> | Its port. The engine's own default when left out |
--superuser <USER> | The account to create it with — postgres or root when left out |
--superuser-password-stdin | Read that account's password from standard input |
--superuser-password-command <COMMAND> | Run this and read that account's password from its output |
--database <NAME> | The database's own name on the server. Asked for when left out |
--role <USER> | The user to create and hand it to. Asked for when left out |
--role-password-stdin | Read the new user's password from standard input instead of generating one |
--role-password-command <COMMAND> | Run this and read the new user's password from its output |
sloop db list
Show every registered database. Never shows a secret
Takes no flags of its own — only the 11 global ones above.
sloop db test
Open a connection to a registered database and report what happened
| Argument | What it is |
|---|---|
[NAME] | Which one. Every registered database when this is left out |
Takes no flags of its own — only the 11 global ones above.
sloop db edit
Change where a registered database is, who connects to it, or how
| Argument | What it is |
|---|---|
<NAME> | Which one |
| Flag | What it does |
|---|---|
--url <URL> | Replace every connection field at once, from a URL |
--engine <ENGINE> | postgres, mysql or mariadb |
--host <HOST> | Host name or address |
--port <PORT> | Port. Defaults to the engine's own |
--database <NAME> | The database's name on the server |
--user <ROLE> | The role to connect as |
--keyring | Keep the password in the OS keyring. The default |
--encrypted-file | Keep it in the Argon2id-encrypted file, for a machine with no keyring |
--env <VARIABLE> | Read it from this environment variable at run time, for automation |
--password-from <COMMAND> | Run this and read the password from its output, for a team password manager |
--password-stdin | Take the password from standard input instead of asking for it |
--test | Connect before saving, and refuse to save if it does not work |
--ssh-host <HOST> | Reach this database through an SSH server, because its own port is not open |
--ssh-port <PORT> | The SSH server's port. 22 when left out. Not the database's port |
--ssh-user <USER> | Who to be on the SSH server. ~/.ssh/config, then your own username, when left out |
--ssh-identity <PATH> | A particular private key, as ssh -i takes it |
--no-ssh | Stop going through an SSH server. The connection becomes a direct one |
--ssh-keyring | Keep the key's passphrase in the OS keyring |
--ssh-encrypted-file | Keep it in the Argon2id-encrypted store, for a machine with no keyring |
--ssh-env <VARIABLE> | Read it from this environment variable at run time, for automation |
--ssh-passphrase-from <COMMAND> | Run this and read the passphrase from its output, for a team password manager |
--ssh-passphrase-stdin | Take the passphrase from standard input instead of asking for it |
sloop db rename
Give a registered database a different name
| Argument | What it is |
|---|---|
<FROM> | What it is called now |
<TO> | What to call it instead |
Takes no flags of its own — only the 11 global ones above.
sloop db remove
Forget a registered database. The server is not touched
| Argument | What it is |
|---|---|
<NAME> | Which one |
Takes no flags of its own — only the 11 global ones above.
sloop db drop
Drop a database on the server. Asks for its name, and keeps nothing
| Argument | What it is |
|---|---|
<NAME> | Which registered database to destroy |
Takes no flags of its own — only the 11 global ones above.
Backups
Taking a copy, seeing what is stored, pruning it, and putting one back.
sloop backup
Dump a database, check every row arrived, and file the copy with a manifest
| Argument | What it is |
|---|---|
[NAME] | Which registered database. Left out when --all is given |
| Flag | What it does |
|---|---|
--all | Back up every registered database, and do not stop at the first failure |
--sequential | Keep every backup, in a directory named for the moment it was taken. The default |
--replace | Keep one backup per database, at backups/<engine>/<name>/latest |
sloop backups
See what has been copied and when, and delete what is past a retention limit
Subcommands: list, prune. Each has its own entry below.
Takes no flags of its own — only the 11 global ones above.
sloop backups list
Show stored backups, newest first, in local time
| Argument | What it is |
|---|---|
[NAME] | Only this database's backups. Every database when left out |
| Flag | What it does |
|---|---|
--check | Hash every dump and compare it with its manifest |
sloop backups prune
Delete backups past a retention limit, after showing which ones
| Argument | What it is |
|---|---|
[NAME] | Only this database's backups. Every database when left out |
| Flag | What it does |
|---|---|
--keep <N> | Keep this many of the newest backups of each database |
--older-than <AGE> | Remove backups older than this — 12h, 30d, 6w |
--include-broken | Remove unfinished and damaged directories too |
sloop restore
Put a stored copy back into a database, replacing what is in it now
| Argument | What it is |
|---|---|
<NAME> | Which registered database to restore into |
| Flag | What it does |
|---|---|
--from <WHEN> | Which backup, by its directory's own name. The newest whole one by default |
Copying
Two commands that are not the same command.
sloop mirror
Copy a database exactly, leaving the destination identical to the source
| Argument | What it is |
|---|---|
<SOURCE> | The registered database to copy. Only ever read |
| Flag | What it does |
|---|---|
--to <NAME> | The registered database to copy it over. Its contents are replaced |
--create <NAME> | Make the destination first, then copy into it. What to call it here |
--table <PATTERN> | Only this table. Repeatable, schema-qualified, and it takes a glob |
--with-references | Bring in the tables the named ones point at, rather than refusing without them |
--safe | Dump to a file first, so a copy that fails can be retried |
--host <HOST> | The server to make it on. The source's own server when left out |
--port <PORT> | Its port. The source's port when the host is the source's, the engine's default otherwise |
--superuser <USER> | The account to create it with — postgres or root when left out |
--superuser-password-stdin | Read that account's password from standard input |
--superuser-password-command <COMMAND> | Run this and read that account's password from its output |
--database <NAME> | The new database's own name on the server. Asked for when left out |
--role <USER> | The user to create and hand it to. Asked for when left out |
--role-password-stdin | Read the new user's password from standard input instead of generating one |
--role-password-command <COMMAND> | Run this and read the new user's password from its output |
sloop sync
Merge a database into another, keeping rows the destination already had
| Argument | What it is |
|---|---|
<SOURCE> | The registered database to copy from. Only ever read |
| Flag | What it does |
|---|---|
--to <NAME> | The registered database to merge it into. Its rows are added to and replaced |
--create <NAME> | Make the destination first, then merge into it. What to call it here |
--table <PATTERN> | Only this table. Repeatable, schema-qualified, and it takes a glob |
--with-references | Bring in the tables the named ones point at, rather than refusing without them |
--safe | Dump the source to a file first, so a merge that fails can be replayed |
--host <HOST> | The server to make it on. The source's own server when left out |
--port <PORT> | Its port. The source's port when the host is the source's, the engine's default otherwise |
--superuser <USER> | The account to create it with — postgres or root when left out |
--superuser-password-stdin | Read that account's password from standard input |
--superuser-password-command <COMMAND> | Run this and read that account's password from its output |
--database <NAME> | The new database's own name on the server. Asked for when left out |
--role <USER> | The user to create and hand it to. Asked for when left out |
--role-password-stdin | Read the new user's password from standard input instead of generating one |
--role-password-command <COMMAND> | Run this and read the new user's password from its output |
Reading
Looking inside a database without writing SQL.
sloop query
Read a database without writing SQL.
Pick a table, tick the columns, choose the test — everything comes off a list and the only thing you type is the value you are looking for. The results open in a grid you can scroll, two hundred rows at a time.
Everything it runs, including --sql, runs inside a transaction the server has been told is read-only. Nothing this command sends can change anything, and it is the server that guarantees that rather than a list of forbidden words.
| Argument | What it is |
|---|---|
[NAME] | Which registered database. Left out, the ones sloop knows are listed |
| Flag | What it does |
|---|---|
--sql <STATEMENT> | Run this one statement instead of building one |
The backup key
Moving the key that every encrypted backup needs between machines.
sloop key
Move the backup encryption key between machines
Subcommands: export, import. Each has its own entry below.
Takes no flags of its own — only the 11 global ones above.
sloop key export
Write the private key out, so losing this machine is not losing the backups
Takes no flags of its own — only the 11 global ones above.
sloop key import
Take a private key exported from another machine
Takes no flags of its own — only the 11 global ones above.
The background service
Registering sloop with the machine, and what it does once it is there.
sloop service
Keep sloop running in the background, so it works with nobody logged in.
Registers sloop with whatever this machine uses to run things at boot — systemd on Linux, launchd on macOS, the Service Control Manager on Windows. Once it is installed and started, it comes back by itself after a restart.
This is for a server, not for a laptop you are working on. On a machine you use yourself, running sloop backup when you want a backup is the simpler thing and nothing here improves on it.
It never opens a port. Nothing listens, nothing can be reached from the network, and what it records is read back with sloop service status from a file on this machine.
Subcommands: install, uninstall, attach, detach, start, stop, schedule, activity, status. Each has its own entry below.
Takes no flags of its own — only the 11 global ones above.
sloop service install
Register sloop with this machine, so it starts at boot.
Writes the unit, the agent or the service entry, whichever this platform uses, and starts it unless told not to. Needs administrator rights, because starting something at boot is a machine-wide change on all three platforms.
| Flag | What it does |
|---|---|
--no-start | Register it, and leave it stopped |
--user <USER> | Run as this account instead of the one installing it. Linux and macOS only |
--interval <SECONDS> | Seconds between one round of readings and the next. 60 by default [default: 60] |
sloop service uninstall
Stop the background service and take it off this machine, keeping what it recorded.
Stops it, removes the unit or the service entry, and removes the key file it reads its credentials with. Nothing sloop has recorded is deleted — attachments and history stay, so installing again picks up where this left off.
Takes no flags of its own — only the 11 global ones above.
sloop service attach
Watch a database. The service picks it up without being restarted.
The attachment is a row sloop's own database holds, and the service reads that list on every round — so attaching reaches one that is already running, and detaching stops it just as quickly.
| Argument | What it is |
|---|---|
<NAME> | The name it is registered under in the global registry |
Takes no flags of its own — only the 11 global ones above.
sloop service detach
Stop watching a database. Everything already recorded about it stays
| Argument | What it is |
|---|---|
<NAME> | The name it is registered under in the global registry |
Takes no flags of its own — only the 11 global ones above.
sloop service start
Start the background service now, rather than waiting for the next boot
Takes no flags of its own — only the 11 global ones above.
sloop service stop
Stop the background service now. It still starts again at the next boot
Takes no flags of its own — only the 11 global ones above.
sloop service schedule
Back this database up on a schedule, with no cron line anywhere.
The service takes the backup, applies the retention policy and prunes what falls outside it. Nothing is written to crontab, Task Scheduler or systemd timers — the schedule is a row sloop's own database holds, and sloop service status says when each database last ran and when it runs next.
| Argument | What it is |
|---|---|
<NAME> | The name it is registered under in the global registry. It has to be attached |
| Flag | What it does |
|---|---|
--every <INTERVAL> | How often: 30m, 6h, 1d, 2w. The same spelling --older-than takes |
--keep <COUNT> | Keep this many of the newest backups, and prune the rest |
--keep-for-days <DAYS> | Prune anything older than this many days |
--off | Stop backing it up. It stays attached and stays sampled |
sloop service activity
What the service has recorded: rows in, rows out and size, by day, week and month.
Rows, not bytes. No engine reports bytes per database — PostgreSQL counts rows, MySQL's byte counters are server-wide — so what is shown is what is true, and every line says which it is. A period nothing was watching reads as having no readings rather than as a zero.
Takes no flags of its own — only the 11 global ones above.
sloop service status
Is it installed, is it running, and when did it last do anything.
Answers honestly when it is stopped, and when it was never installed at all — the two are different states and a monitoring system needs them apart.
Takes no flags of its own — only the 11 global ones above.
This machine
The servers sloop installed, what it can check, and taking it all off.
sloop server
The database servers on this machine — installing one, listing them, and opening sloop's own.
install is engine, then version, then one confirmation, instead of finding the project's website and following its installation instructions: the archive is downloaded by the system's own curl, proved against whatever that project publishes to prove it with, and started on a port that collides with nothing already here. connection is the other direction — where sloop keeps its own state, so you can open it in psql or DataGrip yourself.
Subcommands: install, list, connection. Each has its own entry below.
Takes no flags of its own — only the 11 global ones above.
sloop server install
Download, install, configure and start a database server
| Argument | What it is |
|---|---|
[ENGINE] | postgres, mysql or mariadb. Left out, it is asked for |
| Flag | What it does |
|---|---|
--version <VERSION> | Which version, as the project writes it. Left out, the ones available are listed |
sloop server list
Every server sloop has installed here, and how to reach each one
Takes no flags of its own — only the 11 global ones above.
sloop server connection
Where sloop keeps its own state, so you can open it yourself.
Host, port, database and user, ready to be pasted into psql, DataGrip or anything else that speaks PostgreSQL. The password is kept where this machine keeps secrets and printed only when it is asked for, on a terminal — never into a log file, a document or a pipe.
| Flag | What it does |
|---|---|
--show-password | Print the password too, not only where it is kept |
sloop doctor
Report which client tools are present, and what each registered role may do
| Flag | What it does |
|---|---|
--offline | Do not connect to anything. Reports the client tools and the documented privilege minimums, and asks no server about its grants |
sloop reset
Put this machine back to the moment sloop was installed.
Removes sloop's own database and everything it knows. A PostgreSQL that sloop installed goes with it; one that was already here keeps every other database on it and loses only sloop's. sloop setup is needed again afterwards.
Backups are never deleted, by this or by uninstall.
Takes no flags of its own — only the 11 global ones above.
sloop uninstall
Remove sloop from this machine.
Everything reset does, and then sloop itself.
Takes no flags of its own — only the 11 global ones above.