Authentication
The dorsal auth command group helps you manage your authentication with DorsalHub.
This links your DorsalHub account with the installation of Dorsal you are running, via an API Key you create.
This command group securely saves your API key to log in, removes it to log out, and checks your current session status.
This guide covers the four sub-commands:
login: Log in to DorsalHub and save your API key.gitignore: Secure your project's config file from being committed to Git.logout: Log out by removing your API key from the configuration.whoami: Check the status of your current session.
dorsal auth login
This command authenticates you with DorsalHub by verifying and saving your API key.
By default, the key is saved to your system-wide global config (e.g., ~/.dorsal/dorsal.toml).
Saving to the global config is the most secure method, as it keeps it separate from your project-level config.
Example
-
Run the
dorsal auth logincommand. -
You will be prompted to paste your API key.
-
The API Key is verified by DorsalHub, and it is saved on success to your global config.
-
Alternatively you can save the API Key to your project-level config. This is a
dorsal.tomlfile in your current path.To achieve this, run the
dorsal auth logincommand with the option--project:This will then log you in as before, and in addition it will provide you with a warning message:
Verifying key with DorsalHub... ╭───────── Login Successful ───────────╮ │ │ │ User ID: 1134221 │ │ Name: user │ │ Email: user@example.com │ │ Account Status: Member │ │ │ ╰──────────────────────────────────────╯ Your API key has been saved to the project config: /path/to/project/dorsal.toml ╭─────────────────────── Action Required ─────────────────────────╮ │ │ │ The file 'dorsal.toml' now contains your API key. │ │ │ │ This file must not be committed to Git. │ │ To automatically add this file to your .gitignore, please run: │ │ dorsal auth gitignore │ │ │ ╰──────────────────────────────────────────────────────────────────╯
Environment Variables
You can also log in via an environment variable DORSAL_API_KEY, by setting its value to the API Key.
Note that when both an environment variable and a config-based API Key are available, Dorsal will prefer the environment variable and use it.
Options
-
Pass the key directly as an argument:
-
Save the key to a config in your project folder (e.g.,
./dorsal.toml) with--project
CLI Docs
Usage: dorsal auth login [OPTIONS]
Log in to DorsalHub by providing an API key.
╭─ Options ─────────────────────────────────────────────────────────────╮
│ --apikey TEXT Your DorsalHub API key. If not provided, you will │
│ be prompted. │
│ --project Save the API key to the the project-level dorsal.toml │
│ config file. │
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────╯
dorsal auth gitignore
This is a safety utility command that checks if your project-level config file (e.g., dorsal.toml) is listed in your .gitignore file.
If you ever store your API Key in a config file in your project (e.g. dorsal auth login --project) you can run this command to prevent your secret API key from being accidentally committed to a Git repository.
Example (File not ignored)
If the config file is not found in .gitignore, the command will ask for your consent to add it.
The config file 'dorsal.toml' is not in your .gitignore.
Do you want to add it to the project's root .gitignore file? [y/N]: y
✅ Successfully added '/dorsal.toml' to /path/to/project/.gitignore.
Example (File already ignored)
If the entry is already present in your .gitignore file, the command will notify you and exit.
✅ Entry for 'dorsal.toml' already exists in .gitignore.
╭─────────────────────────────────── File Still Tracked? ────────────────────────────────────╮
│ │
│ Note: If Git is still tracking this file, run the following command to stop tracking it: │
│ git rm --cached dorsal.toml │
│ │
╰────────────────────────────────────────────────────────────────────────────────────────────╯
Options
This command has no options other than --help.
CLI Docs
dorsal auth logout
This command logs you out by removing the API key from your configuration file.
Example
Example (Logging out when the only available key is in the global config)
Warning: You are using a global API key.
Logging out will remove it and affect all your projects.
To confirm, run the command again with the --force flag:
dorsal auth logout --force
CLI Docs
Usage: dorsal auth logout [OPTIONS]
Log out by removing the API key from the local configuration.
╭─ Options ───────────────────────────────────────────────────────────╮
│ --force -f Required to confirm the deletion of a global API key. │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────╯
dorsal auth whoami
Check whether you are currently logged in, and display the logged-in user.
Example
Verifying session with DorsalHub...
╭─────── Authenticated User ──────────╮
│ │
│ User ID: 1134221 │
│ Name: user │
│ Email: user@example.com │
│ Account Status: Member │
│ │
╰──────────────────────────────────────╯
If you are not logged in, it will tell you:
╭───────────── Authentication Required ─────────────╮
│ You are not currently logged in. │
│ │
│ To authenticate, you can either: │
│ 1. Run dorsal auth login │
│ 2. Set the DORSAL_API_KEY environment variable. │
╰───────────────────────────────────────────────────╯
Options
-
Get the raw JSON user info:
CLI Docs
Usage: dorsal auth whoami [OPTIONS]
Check the currently authenticated user and session status.
╭─ Options ───────────────────────────────────────────────────────────╮
│ --json Output the user info as a raw JSON object to stdout for │
│ scripting. │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────╯