> ## Documentation Index
> Fetch the complete documentation index at: https://docs.papermap.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TUI Authentication

> Sign in to Papermap TUI, understand browser login, credential storage, logout, and session behavior.

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

## Sign in

```bash theme={null}
papermap auth login
```

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.

<Check>
  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.
</Check>

## Browser login flow

<Steps>
  <Step title="Start login">
    Run `papermap auth login`. The TUI starts a temporary localhost callback server and opens the Papermap login page.
  </Step>

  <Step title="Authenticate in browser">
    Sign in with your normal Papermap account. The browser preserves the CLI callback URL and a random state value.
  </Step>

  <Step title="Return to terminal">
    Papermap redirects the browser to the local callback with a one-time code. The TUI validates state before exchanging the code.
  </Step>

  <Step title="Store credentials">
    The TUI saves credentials using the local credential store, warms the workspace cache, and prints the signed-in user.
  </Step>
</Steps>

## Login flags

<CodeGroup>
  ```bash Browser theme={null}
  papermap auth login
  papermap auth login --browser
  ```

  ```bash Password theme={null}
  papermap auth login --password
  papermap auth login --password --email you@example.com
  ```

  ```bash URLs theme={null}
  papermap auth login \
    --api-url https://prod.dataapi.papermap.ai \
    --frontend-url https://papermap.ai
  ```
</CodeGroup>

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

## Check current user

```bash theme={null}
papermap auth whoami

# Shortcut
papermap --user
papermap -u
```

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

## Sign out

```bash theme={null}
papermap auth logout
```

Logout clears stored credentials and the local workspace cache.

```text theme={null}
~/.papermap/workspaces.json
```

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.

```text theme={null}
~/.papermap/credentials
```

The file fallback is written with `0600` permissions so only your user can read it.

<Warning>
  Do not commit files from `~/.papermap`. They may contain local session data, workspace cache data, and machine-specific configuration.
</Warning>

## Force file storage

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

```bash theme={null}
PAPERMAP_FORCE_FILE_STORE=1 papermap auth login
```

## 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.

```bash theme={null}
PAPERMAP_ALLOW_UNTRUSTED_FRONTEND=1 \
  papermap auth login --frontend-url https://internal-frontend.example
```

<Warning>
  Only use `PAPERMAP_ALLOW_UNTRUSTED_FRONTEND=1` with frontends you control. It relaxes the default production-host safety check for browser login.
</Warning>

## 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:

```bash theme={null}
papermap auth login
```

## Next steps

<CardGroup cols={2}>
  <Card title="Navigate the TUI" icon="compass" href="/documentation/tui/navigation">
    Learn the active screens, keyboard controls, and command palette.
  </Card>

  <Card title="Configure the TUI" icon="gear" href="/documentation/tui/configuration">
    Set defaults for API URL, frontend URL, thinking traces, selected model, and shell behavior.
  </Card>
</CardGroup>