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

> Configure Papermap TUI API URLs, frontend login URL, thinking traces, selected model, and shell behavior.

Papermap loads configuration from `~/.papermap/config.yaml`. Built-in defaults are used when the file or a setting is missing.

## Config file

```yaml theme={null}
api_url: https://prod.dataapi.papermap.ai
frontend_url: https://papermap.ai
selected_model: gpt-5.4-mini
show_thinking: false
shell:
  windows: pwsh
```

You only need to set values you want to override. Defaults are enough for normal production usage.

## Settings

| Setting | Config key | Default | Purpose |
| - | - | - | - |
| API URL | `api_url` | `https://prod.dataapi.papermap.ai` | Papermap Data API base URL |
| Frontend URL | `frontend_url` | `https://papermap.ai` | Browser login web app base URL |
| Selected model | `selected_model` | Backend default | Model slug used for insight requests |
| Show thinking | `show_thinking` | `false` | Whether reasoning traces show by default |
| Windows shell | `shell.windows` | `pwsh` | Shell used by TUI `!` mode on Windows |

## CLI overrides

Use flags for one-off runs. Flags do not permanently rewrite `config.yaml`.

```bash Launch theme={null}
papermap --api-url https://prod.dataapi.papermap.ai
```

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

```bash Workspaces theme={null}
papermap workspace list --api-url https://prod.dataapi.papermap.ai
papermap workspace create --api-url https://prod.dataapi.papermap.ai
```

## Thinking traces

Set `show_thinking: true` if you want reasoning and tool traces visible by default.

```yaml theme={null}
show_thinking: true
```

You can still toggle traces during a session with `Ctrl+T`.

## Selected model

Papermap persists the model you choose through the model picker or `Tab` cycling.

```yaml theme={null}
selected_model: gpt-5.4-mini
```

If the selected model is empty, unavailable, or removed from your account, the TUI falls back to the backend default.

## Frontend URL safety

Browser login only trusts Papermap production hosts by default.

Allowed without extra configuration:

```text theme={null}
https://papermap.ai
https://www.papermap.ai
```

For internal or development frontends, opt in explicitly:

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

> [!WARNING]
>
> Only enable untrusted frontends for environments you control. This bypasses the default browser-login host allowlist.

## Credential-store environment

Force file-backed credential storage when keyring access is unavailable or undesirable.

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

The fallback credential file lives at:

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

## Windows shell selection

On Windows, shell mode uses PowerShell 7 by default.

```yaml theme={null}
shell:
  windows: pwsh
```

Supported values:

| Value | Shell |
| - | - |
| `pwsh` | PowerShell 7+ (`pwsh.exe`) |
| `cmd` | Command Prompt (`cmd.exe`) |

To use Command Prompt:

```yaml theme={null}
shell:
  windows: cmd
```

If `shell.windows` is `pwsh` and PowerShell 7 cannot be found, Papermap refuses to start and asks you to install PowerShell 7 or change the setting to `cmd`.

> [!NOTE]
>
> The shell is resolved once when the TUI starts. Restart `papermap` after changing `shell.windows`.

## Related local files

| Path | Purpose |
| - | - |
| `~/.papermap/config.yaml` | TUI configuration |
| `~/.papermap/credentials` | File fallback credentials when keyring is not used |
| `~/.papermap/workspaces.json` | Cached workspace metadata |

## Next steps

> [card] [Authentication](https://docs.papermap.ai/documentation/tui/authentication.md)
>
> Understand browser login, password fallback, credential storage, and logout.

> [card] [Troubleshooting](https://docs.papermap.ai/documentation/tui/troubleshooting.md)
>
> Fix configuration, login, workspace, and shell errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.