Skip to main content

Auth and Sessions

Learn how to use authentication and sessions in the LioranDB CLI to securely access and manage your database. Understand how to log in, manage active sessions, and handle authentication across different LioranDB environments.

The CLI exposes auth commands in two equivalent surfaces:

  • top-level commands such as liorandb login
  • namespace aliases such as liorandb auth login

The handlers are the same. The alias exists mostly for discoverability and organization.

liorandb login [username]​

Authenticates with LioranDB and persists a refresh-token session for the selected profile.

Supported forms from the source:

Login examples
liorandb login
liorandb login admin
liorandb login admin --password "super-secret"
printf 'super-secret' | liorandb login admin --password-stdin
liorandb auth login admin

Behavior from the source:

  • interactive login can prompt for missing username and password
  • when no username is supplied and the terminal is interactive, the CLI can also prompt for the URL
  • --password-stdin is supported for automation
  • --password is supported, but the CLI warns because command arguments can leak through shell history or process inspection
  • after successful login, the CLI stores the resulting refresh session for the selected profile

Human-mode login currently prints:

  • a connecting message
  • authenticated username
  • target server
  • target database

JSON-mode login prints:

  • authenticated
  • profile
  • server
  • database
  • principal
  • session

What is persisted after login​

The session store persists these fields per profile:

  • refreshToken
  • sessionId
  • userId
  • username
  • updatedAt

It does not store:

  • your plaintext password
  • access tokens

By default, sessions are written under:

~/.liorandb/state/sessions.json

You can override that root with LIORANDB_STATE_DIR.

How automatic session recovery works​

When a command needs an authenticated client, the helper in src/client/create-client.ts does this:

  1. load the stored refresh token for the selected profile
  2. call client.auth.refresh(...)
  3. save the fresh login response back to the session store
  4. if the session has expired, try re-login from credentials embedded in the connection string
  5. if refresh and re-login both fail, clear stored session state

That is why the CLI can often keep working across commands without asking you to log in every time.

Practical implication:

  • if your stored profile URL contains reusable credentials, the CLI may recover automatically from an expired session
  • if it cannot recover, it will tell you to log in again

liorandb whoami​

Shows the currently authenticated principal for the selected profile.

Human output includes:

  • username
  • user id
  • roles
  • server host
  • profile name

JSON output includes:

  • username
  • user_id
  • roles
  • must_change_password
  • session_id
  • profile
  • server

liorandb sessions​

Lists sessions for the current authenticated user.

Human-mode rows include:

  • current
  • session_id
  • status
  • created_at
  • last_used_at
  • expires_at
  • revoked_at

JSON output includes:

  • profile
  • current_session_id
  • sessions

liorandb revoke-session <session-id>​

Revokes one specific session.

Important source behavior:

  • if you revoke the current session, the CLI also clears the local stored session for the current profile

JSON output includes:

  • revoked
  • session_id
  • profile

liorandb logout​

Revokes the current remote session and clears local session state.

liorandb logout --all​

Revokes all sessions for the current user and clears local session state.

Important source behavior:

  • if no local session is stored, the CLI reports "Already logged out."
  • if the stored session is already expired or unauthorized, the CLI treats that as already logged out and clears the local session store

liorandb change-password​

Changes the password for the current authenticated user.

Supported forms:

liorandb change-password
liorandb change-password --password "new-secret"
printf 'new-secret' | liorandb change-password --password-stdin

Source-backed behavior:

  • --password and --password-stdin are mutually exclusive
  • interactive mode prompts for the new password twice
  • after changing the password, the CLI tries to reauthenticate automatically
  • if reauthentication succeeds, the session store is refreshed
  • if reauthentication fails, the password still changed remotely, but the CLI clears local session state and asks you to log in again

JSON output includes:

  • changed_password
  • reauthenticated
  • profile

First local password-rotation flow​

Typical bootstrap auth flow
printf '%s' "$LIORANDB_BOOTSTRAP_PASSWORD" | liorandb login admin --password-stdin
printf '%s' "$LIORANDB_NEW_PASSWORD" | liorandb change-password --password-stdin
liorandb whoami
liorandb sessions

Expired or revoked sessions​

If the refresh token is no longer valid:

  • the CLI can clear the broken stored session
  • it may recover automatically if your stored connection URL contains reusable credentials
  • otherwise it will tell you to run liorandb login

Why stdin is safer than --password​

Passing passwords directly in command arguments can leak into:

  • shell history
  • process inspection
  • pasted troubleshooting snippets

For automation, prefer:

Safer non-interactive login
printf '%s' "$LIORANDB_PASSWORD" | liorandb login admin --password-stdin