Skip to main content
Authenticate before launching the TUI. Once signed in, papermap restores your session automatically and refreshes tokens when possible.

​
Sign in

The default login flow opens Papermap in your browser. After you authenticate, the web app sends a short-lived one-time CLI code back to a local callback server running on 127.0.0.1. The TUI exchanges that code for normal credentials and stores them locally.
Browser login does not put access_token or refresh_token values in the browser URL. Only the short-lived CLI code returns through the localhost callback.

​
Browser login flow

1

Start login

Run papermap auth login. The TUI starts a temporary localhost callback server and opens the Papermap login page.
2

Authenticate in browser

Sign in with your normal Papermap account. The browser preserves the CLI callback URL and a random state value.
3

Return to terminal

Papermap redirects the browser to the local callback with a one-time code. The TUI validates state before exchanging the code.
4

Store credentials

The TUI saves credentials using the local credential store, warms the workspace cache, and prints the signed-in user.

​
Login flags

Use password login when a browser cannot be opened, such as SSH-only or headless environments.

​
Check current user

If no valid credentials exist, Papermap asks you to run papermap auth login.

​
Sign out

Logout clears stored credentials and the local workspace cache.
The deprecated papermap logout alias still works, but papermap auth logout is the preferred command.

​
Credential storage

Papermap uses the operating system keyring when available. If no supported keyring backend is available, the TUI falls back to a local credential file.
The file fallback is written with 0600 permissions so only your user can read it.
Do not commit files from ~/.papermap. They may contain local session data, workspace cache data, and machine-specific configuration.

​
Force file storage

Set this environment variable when you need to bypass the OS keyring, usually for CI, containers, or controlled headless environments.

​
Custom frontend safety

Browser login only allows https://papermap.ai and https://www.papermap.ai by default. Internal or development frontends require an explicit opt-in.
Only use PAPERMAP_ALLOW_UNTRUSTED_FRONTEND=1 with frontends you control. It relaxes the default production-host safety check for browser login.

​
Session expiration

The TUI checks token expiry before API calls and attempts refresh when possible. If refresh fails, it clears the current app state and sends you back to the signed-out landing message. Run login again:

​
Next steps

Navigate the TUI

Learn the active screens, keyboard controls, and command palette.

Configure the TUI

Set defaults for API URL, frontend URL, thinking traces, selected model, and shell behavior.