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

# Settings file reference

> Complete TOML reference for shared and local Radius project settings.

Radius reads repository settings from two TOML files:

| File                          | Purpose                                 | Version control  |
| ----------------------------- | --------------------------------------- | ---------------- |
| `.radius/settings.toml`       | Shared repository behavior.             | Commit it.       |
| `.radius/settings.local.toml` | Machine-specific overrides and secrets. | Keep it private. |

Both files use `version = 1`. Add the schema URL for editor validation and
autocomplete:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
"$schema" = "https://radiusbrowser.com/schemas/settings.repo.schema.json"
version = 1
```

## Complete example

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
"$schema" = "https://radiusbrowser.com/schemas/settings.repo.schema.json"
version = 1

[environment.variables]
NODE_ENV = "development"
DEV_SERVER_PORT = "5180"

[files]
include = [".env.local", "config/development.json"]

[git]
base_ref = "origin/main"
remote = "origin"
delete_branch_on_archive = false
push_auto_setup_remote = true

[scripts]
startup = "./scripts/open-radius-workspace.sh"
setup = "pnpm install"
archive = "pnpm run cleanup"

[scripts.run.dev]
name = "Development server"
command = "pnpm dev"
```

## Root fields

| Field     | Type    | Required | Description                               |
| --------- | ------- | -------- | ----------------------------------------- |
| `$schema` | String  | No       | Hosted schema URL for TOML-aware editors. |
| `version` | Integer | Yes      | Settings format version. Currently `1`.   |

## Environment

| Field                   | Layer           | Type             | Description                                                  |
| ----------------------- | --------------- | ---------------- | ------------------------------------------------------------ |
| `environment.variables` | Shared or local | Table of strings | Environment values passed to terminals, scripts, and agents. |
| `environment.secrets`   | Local only      | Table of strings | Secret values hidden after saving.                           |
| `environment.unset`     | Local only      | String array     | Shared variable names to remove locally.                     |

Local variables override shared variables by name. `environment.unset` removes
the inherited value even when the shared file changes later.

## Copied files

| Field           | Type         | Default | Description                                                  |
| --------------- | ------------ | ------- | ------------------------------------------------------------ |
| `files.include` | String array | `[]`    | Gitignored file paths or patterns copied into new worktrees. |

A local `files.include` list replaces the shared list. Radius copies regular files
only and always excludes `.radius/settings.local.toml`.

## Git

| Field                          | Type    | Default     | Description                                              |
| ------------------------------ | ------- | ----------- | -------------------------------------------------------- |
| `git.base_ref`                 | String  | Auto-detect | Starting ref for new worktrees.                          |
| `git.remote`                   | String  | `origin`    | Remote used for default push behavior and ref detection. |
| `git.delete_branch_on_archive` | Boolean | `false`     | Delete a non-base local branch after successful archive. |
| `git.push_auto_setup_remote`   | Boolean | `true`      | Let a plain first push set the branch upstream.          |

## Scripts

| Field              | Type   | Default | Description                                                |
| ------------------ | ------ | ------- | ---------------------------------------------------------- |
| `scripts.startup`  | String | Empty   | Command run in a new project or worktree group's terminal. |
| `scripts.setup`    | String | Empty   | Command run visibly after creating a worktree.             |
| `scripts.archive`  | String | Empty   | Command that must succeed before removing a worktree.      |
| `scripts.run.<id>` | Table  | None    | Named command shown in the terminal's **Run…** menu.       |

Each named run command supports:

| Field     | Type    | Description                                                                 |
| --------- | ------- | --------------------------------------------------------------------------- |
| `name`    | String  | Display name. Defaults to the script ID with separators replaced by spaces. |
| `command` | String  | Shell command run from the active workspace.                                |
| `hide`    | Boolean | Hide an inherited command. Use `true` in local settings.                    |

## Local override example

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
"$schema" = "https://radiusbrowser.com/schemas/settings.repo.schema.json"
version = 1

[environment]
unset = ["DEV_SERVER_PORT"]

[environment.variables]
DEV_SERVER_PORT = "5190"

[environment.secrets]
API_TOKEN = "local-secret"

[files]
include = [".env.local", ".npmrc.local"]

[scripts.run.dev]
hide = true
```

<Info>
  The Project Settings page edits local overrides. Open `settings.toml` from the
  page when you want to change shared repository behavior.
</Info>