Skip to content

Command line

The server program is also the maintenance tool. Every command reads the same settings as the server (environment, CONFIG_FILE), and works while the server runs.

docker exec punchlist punchlist <command>
docker exec -it punchlist punchlist <command>     # for commands that read input

sudo -u punchlist env DB_PATH=/var/lib/punchlist/punchlist.db CONFIG_FILE=/etc/punchlist/punchlist.conf \
  /opt/punchlist/punchlist <command>

Or the wrapper from Linux.

$env:DB_PATH = 'C:\ProgramData\Punchlist\punchlist.db'
$env:CONFIG_FILE = 'C:\ProgramData\Punchlist\punchlist.conf'
& 'C:\Program Files\Punchlist\punchlist.exe' <command>

Run with no command (or one the program does not know as a command), it starts the server. Exit codes: 0 done, 1 the command failed (the reason is printed), 2 invalid settings.

punchlist help prints the summary below; this page has the detail. A check in CI keeps this page listing every command.

Usage: punchlist <command>

  export [file]                 Write a full backup as JSON (to stdout without a file).
  export --user <user> [file]   Write one person's data (to stdout without a file).
  import <file> [--replace] [--shift-dates]
                                Load a backup into an empty database (--replace: delete what is
                                there first; --shift-dates: move its dates on by the days since
                                it was made, for a demo seed).
  import --user <file> [user]   Put one person back as a backup had them (from a whole-server
                                backup, say who). Restart the server afterwards.
  migrate-db --to sqlite --path <file>
  migrate-db --to postgres --connection <connection string>
                                Copy everything into another, empty database.
  upgrade-db                    Apply database schema upgrades and exit (for servers
                                running with DB_MIGRATE_ON_START=false).
  snapshot                      Take a snapshot now (into SNAPSHOT_DIR).
  admin reset-password [user]   Give an account (default: admin) a new password to change at login.
  admin add-user <user> [--admin]
                                Add an account; its generated password must be changed at first login.
  admin set-role <user> <role>  Make an account a user, admin or superadmin.
  admin login-link <user>       Print a one-time sign-in link (24 hours).
  oidc unlink <user> [provider] Detach a user's provider accounts (all, or one provider's).
  oidc unbind-all <provider>    Detach every account from a provider (moving to another).
  oidc migration-window <provider> <hours|close>
                                Until it closes, a first sign-in through the provider joins
                                the account with the same username.
  config key                    Print a new CONFIG_KEY for encrypted values.
  config encrypt [value]        Print the value (or standard input) encrypted with CONFIG_KEY,
                                for the environment or CONFIG_FILE: enc:v1:...
  config show                   Every setting with where it comes from (secrets hidden).
  debug-dump [file]             Write a zip for bug reports: recent logs, settings (secrets
                                hidden), versions and database counts (stdout without a file).
  healthcheck                   Exit 0 when the running server answers /healthz.
  --version                     Print the version and build.

Settings come from the same environment variables as the server.

Backups

export

punchlist export [file]
punchlist export --user <username> [file]

Writes a full backup (every account and all data) as JSON, to the file or to standard output. With --user, only that person's data. See backups.

import

punchlist import <file> [--replace] [--shift-dates]
punchlist import --user <file> [username]

Loads a full backup into an empty database; --replace deletes what is there first. With --user, puts one person back as the file had them; from a whole-server backup, say who. Restart the server afterwards.

--shift-dates moves every date in the file's tasks, lists and comments on by the days between the file's exportedAt and today, so a seed made once reads as if made today. The demo server loads its seed this way every night.

snapshot

Takes a snapshot now, into SNAPSHOT_DIR, and prunes old ones to SNAPSHOT_KEEP.

Database

migrate-db

punchlist migrate-db --to sqlite --path <file>
punchlist migrate-db --to postgres --connection "<connection string>"

Copies everything into another, empty database. Then point DB_PROVIDER (and DB_PATH or DB_CONNECTION_STRING) at it and restart. See database.

upgrade-db

Applies database schema upgrades and exits. For servers running with DB_MIGRATE_ON_START=false, whose own database user may not change the schema: run this with one that may, before starting a new version.

Accounts

admin reset-password

punchlist admin reset-password [username]     # default: admin

Prints a new password that must be changed at the next sign-in, and ends the account's other sessions.

admin add-user

punchlist admin add-user <username> [--admin]

Adds an account (a user, or an admin with --admin) and prints its password, to be changed at the first sign-in.

admin set-role

punchlist admin set-role <username> <user|admin|superadmin>

Changes a role; it applies from the person's next request. The last super admin cannot be demoted.

punchlist admin login-link <username>

Prints a link that signs the person in once, within 24 hours. For someone with no password and no working provider. Uses PUBLIC_URL for the address.

Single sign-on

punchlist oidc unlink <username> [provider]

Detaches a person's provider accounts: all of them, or one provider's.

oidc unbind-all

punchlist oidc unbind-all <provider>

Detaches every account from a provider (when moving to another). Accounts and data stay.

oidc migration-window

punchlist oidc migration-window <provider> <hours>
punchlist oidc migration-window <provider> close

Until it closes, a first sign-in through the provider joins the account with the same username. See moving to another provider.

Settings

config show

Every setting, its value (secrets hidden) and where it comes from.

config key

Prints a new CONFIG_KEY for encrypted values.

config encrypt

punchlist config encrypt 'the secret'
echo -n 'the secret' | punchlist config encrypt

Prints the value encrypted with CONFIG_KEY (enc:v1:...), for the environment or the settings file. Reading from standard input keeps the secret out of your shell history.

Diagnostics

debug-dump

punchlist debug-dump [file]

Writes a zip for bug reports: recent logs, settings (secrets hidden), version, time zone, database counts and health; to standard output without a file. See debug dump.

healthcheck

Exits 0 when the running server answers /healthz on ASPNETCORE_HTTP_PORTS. The image's own health check.

--version

Prints the version and the commit it was built from: punchlist 0.2.0+4f1c2e9....