Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Seaus-tech/Aurora-Shell/llms.txt

Use this file to discover all available pages before exploring further.

Aurora Shell includes an optional PIN-protected lock screen that activates on every new terminal session. When enabled, a styled lock screen is displayed before the diagnostics banner, requiring the correct PIN to proceed. On macOS the PIN is stored in the system Keychain so it is never written to disk in plain text. On Windows the PIN is stored in the settings file. The lock screen can also be manually engaged at any time from the command line.

​
How the Lock Works

The lock sequence is handled by the authenticate_user() function, which runs as the very first step when a new terminal session is initialized.
1

Authentication check on open

When the terminal opens, authenticate_user() is called before anything else — including the diagnostics banner.
2

PIN check

The function reads the stored PIN from the macOS Keychain (aurora-shell-pin). If the entry is empty or absent, the lock is skipped entirely and the session continues normally.
3

Lock screen display

If a PIN is found, the screen is cleared and the ASCII lock screen is rendered (colorized via safe_lolcat() on macOS).
4

PIN entry

The user is prompted at the [AUTH] Key: prompt. Input is hidden (no echo). On failure, the terminal prints DENIED and loops back to the prompt indefinitely — there is no lockout limit.
5

Session unlock

On a correct PIN, the screen clears, the logged-in banner is shown, and Show-Aurora() runs to display the diagnostics dashboard.
The lock screen art displayed at step 3 is: 
           .---.
          /     \
         | (00)  |  SYSTEM ENCRYPTED
          \  ^  /
           '---'
     ╔════════════════════════════════════════╗
     ║     AURORA-SHELL SECURITY TERMINAL     ║
     ╚════════════════════════════════════════╝
[AUTH] Key:

​
Setting a PIN

The PIN is configured during the initial installation wizard (run_wizard()). You can also set or update it manually after installation. 
security add-generic-password -a "$USER" -s "aurora-shell-pin" -w "YOUR_PIN" -U
On macOS the -U flag updates an existing entry if one already exists, so running this command is safe for both initial setup and PIN changes. The Keychain service name Aurora uses is aurora-shell-pin. On Windows the PIN is stored as the $AURORA_PW variable in plain text inside aurora-shell_settings.ps1.

​
Manually Engaging the Lock

To lock your terminal at any time without closing the window, run: 
shell.aurora --lock
This clears the screen and re-runs the full authentication and display sequence, exactly as if you had opened a fresh terminal.

​
Logged-In Banner

After a successful PIN entry, Aurora displays a centered confirmation box before showing the diagnostics dashboard. The display name inside the box is sourced from the AURORA_HDR_VAL value in your settings file: 
╭──────────────────────────────────────────────────────────────────╮
│                    Logged in as Aurora-Shell                     │
╰──────────────────────────────────────────────────────────────────╯
The box is padded to 100 characters wide and the label is centered within it. AURORA_HDR_VAL defaults to Aurora-Shell but can be customized in the configuration wizard or by editing ~/.aurora-shell_files/aurora-shell_settings directly.
On Windows, the PIN is stored in plain text inside aurora-shell_settings.ps1. Avoid using a highly sensitive or reused password — treat it as a convenience lock rather than a strong security control.

Build docs developers (and LLMs) love

Get started for freeTalk to us