> For the complete documentation index, see [llms.txt](https://roam-tui.avelino.run/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://roam-tui.avelino.run/tui/configuration.md).

# Configuration

Config file location: `~/.config/roam-tui/config.toml`

## Full example

```toml
[graph]
name = "my-graph"
api_token = "roam-graph-token-..."

[ui]
theme = "dark"
sidebar_default = true
sidebar_width_percent = 35

[keybindings]
preset = "vim"

[keybindings.bindings]
quit = "Ctrl+q"
search = "Ctrl+f"

[sync]
dir = "~/.config/roam-tui/sync"
db_dir = "~/.config/roam-tui/.chrondb"
remote = "git@github.com:user/notes.git"
```

## Options

### `[graph]` — required

| Key         | Type   | Description                                |
| ----------- | ------ | ------------------------------------------ |
| `name`      | string | Your Roam graph name (as shown in the URL) |
| `api_token` | string | API token with read/write access           |

### `[ui]` — optional

| Key                     | Type   | Default  | Description                             |
| ----------------------- | ------ | -------- | --------------------------------------- |
| `theme`                 | string | `"dark"` | Color theme: `"dark"` or `"light"`      |
| `sidebar_default`       | bool   | `true`   | Show sidebar on startup                 |
| `sidebar_width_percent` | u16    | `35`     | Sidebar width as percentage of terminal |

### `[keybindings]` — optional

| Key      | Type   | Default | Description                                    |
| -------- | ------ | ------- | ---------------------------------------------- |
| `preset` | string | `"vim"` | Base preset: `"vim"`, `"emacs"`, or `"vscode"` |

### `[keybindings.bindings]` — optional

Override individual keys from the preset. Keys are action names, values are key strings.

```toml
[keybindings.bindings]
quit = "Ctrl+q"
search = "Ctrl+f"
move_up = "Ctrl+k"
```

See [Keybindings](/tui/keybindings.md) for all available actions and key format.

### `[sync]` — optional

| Key      | Type   | Default                       | Description                                                               |
| -------- | ------ | ----------------------------- | ------------------------------------------------------------------------- |
| `dir`    | string | `~/.config/roam-tui/sync`     | Directory for synced markdown files                                       |
| `db_dir` | string | `~/.config/roam-tui/.chrondb` | ChronDB storage directory                                                 |
| `remote` | string | `""`                          | Git remote URL for markdown backup (e.g. `git@github.com:user/notes.git`) |

See [Sync](/cli/sync.md) for usage details.

## Environment variables

Every config option can be set via environment variables with the `ROAM_` prefix. Use `__` (double underscore) for nesting.

| Variable                          | Config equivalent          |
| --------------------------------- | -------------------------- |
| `ROAM_GRAPH_NAME`                 | `graph.name`               |
| `ROAM_GRAPH_API__TOKEN`           | `graph.api_token`          |
| `ROAM_UI_THEME`                   | `ui.theme`                 |
| `ROAM_UI_SIDEBAR__DEFAULT`        | `ui.sidebar_default`       |
| `ROAM_UI_SIDEBAR__WIDTH__PERCENT` | `ui.sidebar_width_percent` |
| `ROAM_KEYBINDINGS_PRESET`         | `keybindings.preset`       |
| `ROAM_SYNC_DIR`                   | `sync.dir`                 |
| `ROAM_SYNC_DB__DIR`               | `sync.db_dir`              |
| `ROAM_SYNC_REMOTE`                | `sync.remote`              |

Environment variables override file values. This is useful for keeping tokens out of config files:

```bash
export ROAM_GRAPH_API__TOKEN="roam-graph-token-..."
roam
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://roam-tui.avelino.run/tui/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.