# Add a Config File to a Textual App

Yes. An agent adds a TOML config file to your Textual app in the platform config directory, maps its keys onto CLI flags and view defaults, tests it, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-config-file/textual/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the app is started before it adds a file that changes that. In an app laid out like Textualize/toolong, `pyproject.toml` is a Poetry project at version 1.5.0 for Python `^3.8`, depending on `click ^8.1.7` and `textual ^0.58.0`, with `textual-dev` in the dev group and one script, `tl = toolong.cli:run`. `cli.py` is a `click.command` taking `FILE1 FILE2` arguments, `-m/--merge` and `-o/--output-merge PATH`; with no files on a terminal it prints the help, and with piped input it copies stdin to a temporary file and relaunches itself in a child process. `ui.py` defines `UI(App)`, which takes `file_paths`, `merge` and `save_merge`, and `LogScreen`, which opens one tab per file or a merged tab. `log_view.py` holds the per-file state as reactives: `show_line_numbers` (off), `tail` and `can_tail`, bound to `ctrl+l` and `ctrl+t`; `find_dialog.py` has `Case sensitive` and `Regex` checkboxes; `help.py` renders a Markdown help screen. There is no tests directory, no configuration and nothing persists between runs.

It adds `src/toolong/config.py`: a `Config` dataclass with `merge`, `show_line_numbers`, `tail`, `find_regex` and `find_case_sensitive`, all defaulting to today's behaviour, and a `load()` that reads `config.toml` from `platformdirs.user_config_dir("toolong")`, which is `~/.config/toolong` on Linux, with `TOOLONG_CONFIG` as an override for a different path. Python 3.11 ships `tomllib`; for the 3.8 to 3.10 range the project supports, `tomli` is added with a `python = "<3.11"` marker alongside `platformdirs` in the Poetry dependencies. A missing file means defaults. A file that does not parse prints one line to stderr naming the path and the error and continues with defaults, and an unknown key is reported the same way rather than ignored, since a typo in a config file is otherwise invisible.

The precedence is flag, then file, then built-in. `cli.py` changes its two options to default to `None`, adds `--config PATH` and `--init-config`, which writes a commented template to the config path and exits, and passes a `Config` into `UI`. `UI` hands it to `LogScreen`, which sets `show_line_numbers` and `tail` on each `LogView` it creates (`tail` only where `can_tail` holds, which merged views never do), and `FindDialog` reads the two find defaults when it mounts. The help screen in `help.py` gains a `Configuration` section listing the keys and the path, and the README gets the same.

Tests are new to the project, so the agent adds `pytest` and `pytest-asyncio` to the dev group and a `tests/` directory: `test_config.py` loads from a `tmp_path`, checks the env override, the unknown-key warning and the bad-file fallback; `test_ui.py` uses Textual's `App.run_test()` pilot to start `UI` on a temporary log file with `show_line_numbers = true` and asserts the `LogView` reactive is on, then presses `ctrl+l` and asserts it turns off, which proves the file sets the starting state without taking over the binding. `poetry run pytest` passes before the pull request opens.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a TOML config file to this Textual app. Read pyproject.toml, src/toolong/cli.py, src/toolong/ui.py, src/toolong/log_view.py, src/toolong/find_dialog.py, src/toolong/help.py and the README first. Add src/toolong/config.py with a Config dataclass for merge, show_line_numbers, tail, find_regex and find_case_sensitive, loaded from config.toml under platformdirs.user_config_dir for toolong or the path in TOOLONG_CONFIG, using tomllib on 3.11+ and tomli below. Report an unparseable file or an unknown key on stderr and fall back to defaults. Make the CLI flags default to None so a flag beats the file and the file beats the built-in default, add --config PATH and --init-config, and pass the Config into UI so LogView and FindDialog start with its values. Document the keys in help.py and the README. Add pytest with tests for loading, the env override, the warnings, and a run_test pilot that starts the app with show_line_numbers on and toggles it. Run poetry run pytest and open a pull request that shows the template file --init-config writes.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `src/toolong/config.py`, `tests/test_config.py` and `tests/test_ui.py`, changes `cli.py`, `ui.py`, `log_view.py`, `find_dialog.py`, `help.py`, the README and `pyproject.toml` (two runtime dependencies, two dev dependencies, the lock file). Its description shows the template `--init-config` writes, the precedence rule in one sentence, and the pytest output.

A reviewer runs `tl --init-config`, edits the file, starts the app on a log and watches line numbers come up without the flag, then passes `--merge` on the command line against a file that says `merge = false` to confirm the flag wins. They read `config.py` for what happens on a bad file, since a log viewer that refuses to start over a typo is worse than one with defaults, and decide whether the stderr line is enough or the app should show a notification once it is up.

The keys are the ones the app already has state for. A new preference is one dataclass field and one place that reads it.

## Run it on every Textual app gaining a preference

An automation on the Project with a `linear` trigger on `linear.issue.labeled` and the label `preference` starts one run per setting a user asks to keep between runs. The trigger adds the issue after the prompt and fills in no placeholder, so the prompt tells the agent to read the setting from the issue, add it to `Config`, wire it where the app already holds that state, and extend the template and the tests.

A team maintaining several Textual tools sends this body once per repository from its own server, each `POST /o/{org}/sessions` naming that repository in `resources` with a `request_id` that is a UUID v5 of the repository name, so a retried call returns the run already started. Each run reads its own CLI and reactives and chooses the keys that app can honour.

## Why run it on Rush?

A config file is cheap to add and easy to get subtly wrong: a flag that no longer overrides the file, a reactive set after the widget mounted, a parse error that takes the app down. The agent makes the change against the real app in its own sandbox, drives it with Textual's pilot, runs the new tests on the project's Python range, and keeps the output with the pull request.

A reviewer reads a dataclass, a loader and two tests. A team with several terminal tools starts the same request across all of them, and each pull request names the keys that tool can honour.

## Frequently asked questions

### Where does the file live?

In the per-user config directory `platformdirs` resolves for the app name, `~/.config/toolong/config.toml` on Linux and the platform's equivalent elsewhere, or wherever `TOOLONG_CONFIG` or `--config` points. `--init-config` writes a commented template there.

### Which wins, the flag or the file?

The flag. The CLI options default to `None` so the loader can tell an absent flag from an explicit one, then the file applies, then the built-in default. The test suite checks that order for `merge`.

### What happens with a broken file?

The app prints one line naming the file and the error, ignores it and starts with defaults; an unknown key gets the same treatment. A terminal tool should never refuse to open a log over its own settings.

### Does it add a dependency for TOML?

Only below Python 3.11, where `tomli` is pulled in with a version marker; 3.11 and later use the standard library's `tomllib`. `platformdirs` is the other addition, for the config directory.

### Why not a Textual feature for this?

Textual gives the app its reactives and bindings but no settings file, and the keys here are the app's own flags and view state, so the mapping is specific to the app. The loader is a few dozen lines and has no framework dependency.

## More Textual jobs

- [Add Dependabot to a Textual App](https://getrush.ai/run/add-dependabot/textual/)
- [Add GitHub Actions CI to a Textual App](https://getrush.ai/run/add-github-actions-ci/textual/)
- [Persist User Settings in a Textual App](https://getrush.ai/run/add-persistent-settings/textual/)

## The same job on other stacks

- [Add a Config File to a Tokio Server](https://getrush.ai/run/add-config-file/tokio/)
- [Add a Config File to a Click CLI](https://getrush.ai/run/add-config-file/click/)
- [Add a Config File to a Go CLI](https://getrush.ai/run/add-config-file/go-cli/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
