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

<CodeGroup>
  ```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
  ```
</CodeGroup>

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

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

<Info>
  The shell is resolved once when the TUI starts. Restart `papermap` after changing `shell.windows`.
</Info>

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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/documentation/tui/authentication">
    Understand browser login, password fallback, credential storage, and logout.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/documentation/tui/troubleshooting">
    Fix configuration, login, workspace, and shell errors.
  </Card>
</CardGroup>