Showcase server CLI

The Showcase server is also its own administration tool. Given a subcommand it opens the configured database, updates it if needed, performs the action and exits. The server itself does not start. (cert:ensure is the exception: it does not touch the database.)

Use it for recovery operations that must not depend on a working browser session: a lost admin password, a locked-out account, a first admin on a machine that has no mail server.

The running server is unaffected

Subcommands act directly on the database and exit. You do not need to stop the service first, and running one does not restart it.

Passwords on the command line

users:create-admin and users:reset-password take the password as a command-line argument. While the command runs, other users of the computer can see its arguments, and the command stays in your shell history (on Ubuntu, sudo may also record the command line in the system log). Run these commands only on a computer you control, set a temporary password, and have the user change it in the Editor straight away. Passwords must be at least 12 characters.

Run showcase-server --help to list the subcommands.

Running the CLI

The command is showcase-server. Where you find it depends on the platform.

Linux

The Debian package puts it on your PATH:

showcase-server users:create-admin --email alice@example.com --password 'SecurePassword123'

The database is owned by the mt-showcase-server service account, so the command re-runs itself as that user and tells you it has done so:

showcase-server: re-running as mt-showcase-server (owner of the database)

You will be prompted for your sudo password.

Windows

The installer does not add the server folder to PATH. Call the script by its full path from an ordinary Command Prompt:

"C:\Program Files\MT Showcase\server\showcase-server.cmd" users:create-admin --email alice@example.com --password "SecurePassword123"

In PowerShell, put the call operator & in front of the quoted path.

Windows runs the server as the signed-in operator rather than a service account, so there is no privilege escalation step. Run the command as the same Windows user MT Showcase runs as: the database is in that user's profile, and running it as a different user acts on a different, possibly empty, database.

macOS

The macOS build does not stage the showcase-server wrapper — call the bundled Node runtime against the server entry point directly, with RACK_ENV=production_macos set so it loads the same configuration the app itself uses (including the database location):

cd "/Applications/MT Showcase.app/Contents/Resources/server"
RACK_ENV=production_macos "../node/bin/node" api/dist/index.js \
  users:create-admin --email alice@example.com --password 'SecurePassword123'

The database is in your own home directory (~/.mt-showcase/showcase.db), so no escalation is needed.

Always set RACK_ENV=production_macos

Without RACK_ENV=production_macos the command does not load the macOS configuration, so it appears to succeed but acts on the wrong database, not ~/.mt-showcase/showcase.db. It can also write a database file inside the application bundle, which breaks the app's code signature so that macOS refuses to open it. NODE_ENV=production alone does not select the macOS configuration.

Older installations (Linux and Windows)

If showcase-server is not present on Linux or Windows, your build predates it. Invoke the server's entry point directly. Older builds may not have every subcommand listed below:

# Linux
cd /opt/mt-showcase-<version>/server
sudo -u mt-showcase-server env NODE_ENV=production \
  node/bin/node api/dist/index.js users:create-admin --email … --password …

On Windows use node\node.exe api\dist\index.js … from C:\Program Files\MT Showcase\server with NODE_ENV=production_win.

Subcommands

users:create-admin

showcase-server users:create-admin --email <email> --password <password> [--display-name <name>]

Creates a role=admin status=active user, bypassing the setup wizard. Use it to seed the first administrator, or to regain access when no admin can log in.

Idempotent when the email already belongs to an active admin — exits 0 and changes nothing.
Refused with exit 65 when the email exists with a different role or status. The CLI never silently promotes, demotes, or re-enables an account.

users:reset-password

showcase-server users:reset-password --email <email> --password <new-password>

Overwrites the user's password and clears any active lockout (failed_login_count, locked_until). Exits 66 if no such user exists.

users:disable / users:enable

showcase-server users:disable --email <email>
showcase-server users:enable --email <email>

Toggles the account between active and disabled. A disabled user cannot sign in. Both are idempotent: running one against an account already in that state exits 0 and changes nothing.

users:unlock

showcase-server users:unlock --email <email>

Clears failed_login_count and locked_until for an account that tripped the lockout threshold. Equivalent to the Unlock button in the admin portal. Idempotent.

keys:rotate-signing

showcase-server keys:rotate-signing

Creates a new token signing key and keeps the previous key valid for 30 days, so sessions already signed in are not interrupted. Prints the new key ID. Only one previous key is kept: rotating twice within 30 days ends the older key's validity at once.

This does not end active sessions

To sign everyone out at once, for example after a suspected compromise, use Revoke all sessions on the Editor's Security page instead; see Users and security. That revokes every session and rotates the signing key, and the previous key stops working immediately.

cert:ensure

showcase-server cert:ensure

Generates the self-signed TLS certificate the server uses for HTTPS, or reuses the existing one if it is still valid and matches its key, and prints the certificate's file path. Installers run this before starting the service so the certificate exists in time to be added to the operating system's trusted certificates. If tls_cert_path and tls_key_path are set in the configuration file, it generates nothing and prints that path. It reads only the configuration file, not a certificate installed on the Network & Public Access page, and it does not touch the database.

showcase-server widget-library:dedupe [--apply] [--json]

Reports exact-duplicate Widget Library entries, or merges them when run with --apply. Without --apply it only reports what a merge would do — the merge cannot be undone without restoring the database, so review the report first. --json writes the report as JSON instead of text.

assets:repair-quoting

showcase-server assets:repair-quoting [--apply] [--json]

Reports asset references stored in an over-wrapped form, or rewrites them into their canonical form when run with --apply. Without --apply it only reports. The player reads both forms correctly, so this is not urgent to run, but it keeps stored and exported references in their intended form. --json writes the report as JSON instead of text.

Exit codes

Scripts can branch on the exit status; every subcommand uses the same set.

Code	Meaning
`0`	Success, or nothing to change (these subcommands are idempotent). `--help` also exits `0` on Linux.
`1`	Unhandled error
`64`	Usage or validation error: a missing or malformed flag, an unknown subcommand, a password shorter than 12 characters, or no subcommand at all. On Windows, `--help` also exits `64`.
`65`	The email exists with a conflicting role or status
`66`	User not found

Audit trail

The users:* subcommands and keys:rotate-signing record what they change in the audit log, with events named cli.users.* and cli.keys.rotate_signing and the IP address shown as cli, so recovery actions appear alongside actions taken in the Editor. Running users:create-admin, users:disable or users:enable when there is nothing to change records no event. cert:ensure, widget-library:dedupe and assets:repair-quoting do not write to the audit log. There is no separate CLI log to collect.