CLI

Tinyauth offers a simple CLI to configure the app and manage users.

Commands

All commands can be run from the standalone Tinyauth binary:

./tinyauth [options]

Alternatively, when running the app through Docker:

docker run -i -t --rm ghcr.io/steveiliop56/tinyauth:v5 [options]

Note

When using Docker Compose, the command docker compose run tinyauth [options] can also be used.

Main Command

The main command starts the API and web UI, waiting for incoming connections. All options are configurable with CLI flags or environment variables. A complete list of configuration options is available on the configuration page.

Healthcheck command

The health check command verifies if Tinyauth is running correctly:

Docker

docker compose exec tinyauth healthcheck

Binary

./tinyauth healthcheck

By default, it will use http://127.0.0.1:3000 to check the health endpoint. The URL will automatically change if you set the TINYAUTH_SERVER_PORT and the TINYAUTH_SERVER_ADDRESS environment variables. You can also specify a custom URL with:

Docker

docker compose exec tinyauth healthcheck http://tinyauth.example.com

Binary

./tinyauth healthcheck http://tinyauth.example.com

Note

It is advised to not use the healthcheck command with the public URL of Tinyauth as it can result in connection issues. It is recommended to use the healthcheck command with the internal URL of Tinyauth (e.g., http://127.0.0.1:3000).

Create User Command

The create command simplifies user creation. To create a user interactively:

Docker

docker run -i -t --rm ghcr.io/steveiliop56/tinyauth:v5 user create --interactive

Binary

./tinyauth user create --interactive

This launches an interactive TUI to input a username and password, generating the username:hash format required by Tinyauth. It can also format the user for Docker Compose or environment variables. For non-interactive creation:

Docker

docker run -i -t --rm ghcr.io/steveiliop56/tinyauth:v5 user create --username user@example.com --password password

Binary

./tinyauth user create --username user@example.com --password password

Flag	Description	Default	Required
--username	Username for creating the user.	“	yes
--password	Password for creating the user.	“	yes
--docker	Format output for Docker Compose or environment variables.	false	no
--interactive	Use an interactive TUI for user creation.	false	no

Verify User Command

The verify command checks if a username and password match the username:hash. For interactive verification:

Docker

docker run -i -t --rm ghcr.io/steveiliop56/tinyauth:v5 user verify --interactive

Binary

./tinyauth user verify --interactive

A TUI prompts for the username:hash:secret, username, password and optional TOTP code, verifying the credentials. For non-interactive verification:

Docker

docker run -i -t --rm ghcr.io/steveiliop56/tinyauth:v5 user verify --user 'user@example.com:$2a$10$UdLYoJ5lgPsC0RKqYH/jMua7zIn0g9kPqWmhYayJYLaZQ/FTmH2/u' --username user@example.com --password password

Binary

./tinyauth user verify --user 'user@example.com:$2a$10$UdLYoJ5lgPsC0RKqYH/jMua7zIn0g9kPqWmhYayJYLaZQ/FTmH2/u' --username user@example.com --password password

Note

Use quotes (') in bash shells to ensure the hash is passed correctly.

Flag	Description	Default	Required
--user	The username:hash combination to verify.	“	yes
--username	Username for verification.	“	yes
--password	Password for verification.	“	yes
--interactive	Use an interactive TUI for verification.	false	no
--totp	Optional TOTP code for verification.	“	no

Generate TOTP Command

Tinyauth can auto-generate TOTP codes for you, the combination is username:hash:secret. You can generate a TOTP user with:

Docker

docker run -i -t --rm ghcr.io/steveiliop56/tinyauth:v5 totp generate --interactive

Binary

./tinyauth totp generate --interactive

This prompts for the current username:hash and generates a username:hash:secret along with a QR code for adding to an authenticator app. For non-interactive generation:

Docker

docker run -i -t --rm ghcr.io/steveiliop56/tinyauth:v5 totp generate --user 'user@example.com:$2a$10$UdLYoJ5lgPsC0RKqYH/jMua7zIn0g9kPqWmhYayJYLaZQ/FTmH2/u'

Binary

./tinyauth totp generate --user 'user@example.com:$2a$10$UdLYoJ5lgPsC0RKqYH/jMua7zIn0g9kPqWmhYayJYLaZQ/FTmH2/u'

Note

Use quotes (') in bash shells to ensure the hash is passed correctly.

Note

Due to the way the QR code library works in Tinyauth, the QR code may be massive and may not fit on a standard screen. If this happens, you can try resizing your terminal window or using a different terminal emulator.

Flag	Description	Default	Required
--user	The current username:hash combination.	“	yes
--interactive	Use an interactive TUI for creating the TOTP user.	false	no