# Upgrade a Textual App to the Current Textual Release

Yes. An agent moves your Textual app across the breaking releases since the version it pins, runs it headless with Pilot until it works, and opens a pull request.

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

## What the agent does

The agent reads what the app pins and what it touches before it changes a version, because Textual's breaking releases are listed per feature and an app only pays for the ones it uses. In an app laid out like Textualize/toolong, `pyproject.toml` is a Poetry project with `python = "^3.8"`, `textual = "^0.58.0"`, `click` and `typing-extensions`, a `textual-dev` dev dependency and one script, `tl = "toolong.cli:run"`; `poetry.lock` resolves Textual to 0.58.0 and Rich to 13.7.1. There are no tests, no `.github` directory and no CI. The `src/toolong` package is eighteen modules. `ui.py` defines `UI(App)`, whose `on_mount` sets `self.ansi_theme_dark` to Rich's `DIMMED_MONOKAI`, awaits `push_screen(LogScreen())` and focuses the `LogLines` widget. `log_lines.py` is the heavy one: a `ScrollView` with `render_line` returning a `Strip`, `Strip.blank` and `Strip.join`, `get_component_rich_style` for the pointer, line-number and filter highlights, an `LRUCache` from `textual.cache`, `@work(thread=True)` workers that post `NewBreaks`, `ScanProgress` and `ScanComplete` messages, and handlers on `scrollbar.ScrollTo`, `ScrollUp` and `ScrollDown`. `find_dialog.py` uses `Input` and `Checkbox` with a `Suggester`, `goto_screen.py` a `ModalScreen` with an `Integer` validator, `help.py` a `Markdown` widget, and `log_view.py` `TabbedContent`, `Lazy` and `Binding`. The `DEFAULT_CSS` blocks lean on `$primary`, `$secondary`, `$accent`, `$success`, `$warning` and `$background`.

Against that list the agent reads Textual's changelog from 0.58.0 up to the current release and keeps only the entries that touch those names. The ones it finds are the removal of `App.dark` and the new theme system in 0.86.0, which also changed the built-in CSS variables the stylesheets use; `push_screen` and `Screen.dismiss` returning awaitables in 0.71.0, which `ui.py` already awaits; the `Input` reactives `cursor_position` and `view_position` removed in 0.89.0; the default quit key moving to ctrl+q in 1.0.0; the `Markdown` component classes moving to `MarkdownBlock` in 5.0.0; the line API no longer painting a background behind blank segments in 6.0.0, which matters to a widget that builds every row from `Strip.blank`; Python 3.8 support ending in 6.3.0; and alpha keys with modifiers being lowercased in 6.8.0, which changes how a binding such as ctrl+shift+f is spelled. Each one becomes a line in the pull request with the file it affects.

The upgrade itself is one `poetry add textual@latest`, a Python floor raised to what the new Textual's metadata requires, a refreshed `poetry.lock`, and then the app run headless until it stops failing. The agent writes `tests/test_smoke.py` with a `pytest` that opens a sample log file through `UI.run_test()`, waits for the `LogLines` widget, presses the keys bound in `LogScreen.BINDINGS` and the find dialog, and asserts no exception reached the app; each traceback is fixed where it points, such as `ansi_theme_dark` on the new theme API, the `Strip.blank` background in `render_line`, or a component class the `Markdown` help pane no longer has. Because the app relaunches itself in a subprocess with `TEXTUAL_ALLOW_SIGNALS` set when input is piped, `cli.py` is run both ways: with a file argument and with a file on stdin. `textual run --dev` is used for a last look at the stylesheet with the new variables.

The pull request carries `pyproject.toml`, `poetry.lock`, the modules that needed a change, the new smoke test and a `pytest` dev dependency, and nothing else. The agent does not reformat files it did not have to touch, and it leaves `click`, `typing-extensions` and `textual-dev` on their existing constraints unless the new Textual refuses them.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Upgrade this Textual app from the version pinned in pyproject.toml to the current Textual release. Read pyproject.toml, poetry.lock and every module under src/ first, and list the Textual APIs the app uses: App attributes, Screen and ModalScreen, Strip and render_line, workers, scrollbar messages, widgets, validators, bindings and the CSS variables in DEFAULT_CSS. Read Textual's changelog from the pinned version to the current one and keep the breaking entries that touch those APIs. Run poetry add textual@latest, raise the Python floor if the new release requires it, and refresh poetry.lock. Write a pytest smoke test that opens a sample log file with App.run_test, waits for the main widget, presses the keys in the app's bindings and the find dialog, and asserts no exception reached the app; fix each traceback where it points until the test passes, and also run the CLI with a file argument and with piped stdin. Open a pull request that lists each breaking change you handled with the file it touched, and the test output. Do not change unrelated dependencies or reformat untouched files.",
  "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 changes `pyproject.toml` and `poetry.lock`, the modules where a Textual API moved, and adds `tests/test_smoke.py`. Its description is a table: one row per breaking change between the pinned and the new release that the app actually hit, with the changelog version, the file and the fix. Entries the app does not use are listed once at the bottom as checked and not applicable, so a reviewer can see what was ruled out.

The smoke test output from the sandbox is pasted below the table, along with the two CLI invocations, so the first thing a reviewer reads is that the app opens a file, scrolls, finds and quits on the new release. There is no CI in the repository, so the test is the check; the description notes that a workflow running `poetry install` and `pytest` is a one-file follow-up.

Before merging, a reviewer checks the app in a real terminal, because a headless run cannot judge colours: the theme the app now sets in place of `ansi_theme_dark`, the look of blank rows after the 6.0.0 line API change, and the spelling of any modifier bindings after 6.8.0.

## Run it on every Textual release

The same work on a schedule keeps the gap small. An automation on the Project with a `schedule` trigger set to run on Monday morning and the prompt "check whether a new Textual release exists; if so, upgrade to it, run the smoke test and open a pull request listing the breaking changes handled" starts one run a week. Only a run that finds a new release opens a pull request; the rest end with a note. The automation's own `max_runs_per_hour` cap applies to it.

A team with several Textual apps sends this body once per repository from its own server, each a `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name and the target Textual version, so a retried call returns the run already started. Each run reads its own pin: an app that already has snapshot tests runs them instead of writing a smoke test, and one on `uv` or `hatch` uses that tool's lock command in place of Poetry's.

## Why run it on Rush?

A framework upgrade across major versions is a long list of small, specific changes, and the hard part is matching the changelog to the code: which of the removed names this app calls, in which file, and what the replacement is. The agent reads both sides and runs the app headless after each fix in its own sandbox, so it is working from tracebacks rather than from a guess about what might break.

The smoke test and the CLI runs stay with the run and are pasted into the pull request, so the review is of an app that has been opened, scrolled and quit on the new release. Several apps get the same upgrade at once, each against its own list of APIs.

## Frequently asked questions

### Why raise the Python floor?

Because Textual dropped Python 3.8 in 6.3.0, and the app's `pyproject.toml` still allows it. Poetry refuses to resolve a lock that promises 3.8 support with a dependency that does not have it, so the floor moves to what Textual's own metadata requires, and the pull request says so.

### What if the app has no tests?

The agent writes one smoke test with `App.run_test` and Textual's `Pilot`, which drives the app headless: it opens a sample file, presses the bound keys and checks that no exception reached the app. That is enough to catch an API that no longer exists; it is not a visual check, which is why the pull request asks for one in a terminal.

### Will it change how the app looks?

Possibly. The 0.86.0 theme system replaced `App.dark` and changed built-in CSS variables, and 6.0.0 stopped painting a background behind blank segments in the line API. The agent keeps the stylesheet variables the app already uses and fixes what the smoke test catches, and lists both changes for a reviewer to look at in a real terminal.

### Can I stop at a smaller version?

Yes. Say the target version in the prompt and the agent reads the changelog only up to it. The table in the pull request is the same shape, so a later run from that version to the current one picks up where this one stopped.

## More Textual jobs

- [Write Pytest Tests for a Textual Terminal App](https://getrush.ai/run/write-pytest-tests/textual/)
- [Write Snapshot Tests for a Textual App](https://getrush.ai/run/write-snapshot-tests/textual/)
- [Add Command Palette Commands to a Textual App](https://getrush.ai/run/add-command-palette/textual/)

## More jobs like this: Upgrade dependencies weekly

- [Upgrade TypeORM from 0.2 to 0.3](https://getrush.ai/run/upgrade-typeorm/typeorm/)
- [Upgrade Python Dependencies with uv in a FastAPI App](https://getrush.ai/run/upgrade-uv-dependencies/fastapi/)
- [Upgrade a React App From Vite 5 to the Current Vite Major](https://getrush.ai/run/upgrade-vite/vite/)

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