TUI Configuration

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

Config file

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.

papermap --api-url https://prod.dataapi.papermap.ai

papermap auth login \
  --api-url https://prod.dataapi.papermap.ai \
  --frontend-url https://papermap.ai

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.

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.

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:

https://papermap.ai
https://www.papermap.ai

For internal or development frontends, opt in explicitly:

PAPERMAP_ALLOW_UNTRUSTED_FRONTEND=1 \
  papermap auth login --frontend-url https://internal-frontend.example

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.

PAPERMAP_FORCE_FILE_STORE=1 papermap auth login

The fallback credential file lives at:

~/.papermap/credentials

Windows shell selection

On Windows, shell mode uses PowerShell 7 by default.

shell:
  windows: pwsh

Supported values:

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

To use Command Prompt:

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.

The shell is resolved once when the TUI starts. Restart papermap after changing shell.windows.

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

Getting Started

Terminal UI

Embedding

Multi-Tenancy

TUI Configuration

Config file

Settings

CLI overrides

Thinking traces

Selected model

Frontend URL safety

Credential-store environment

Windows shell selection

Next steps

Authentication

Troubleshooting

​Config file

​Settings

​CLI overrides

​Thinking traces

​Selected model

​Frontend URL safety

​Credential-store environment

​Windows shell selection

​Related local files

​Next steps

Authentication

Troubleshooting

Config file

Settings

CLI overrides

Thinking traces

Selected model

Frontend URL safety

Credential-store environment

Windows shell selection

Related local files

Next steps