# Add Command Palette Commands to a Textual App

Yes. An agent writes a command Provider that exposes your app's actions in Textual's command palette, registers it on COMMANDS, documents the key, and opens a PR.

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

## What the agent does

The agent reads the app's actions before exposing them. In an app laid out like Textualize/toolong, `pyproject.toml` pins `textual` `^0.58.0` (0.58.0 in `poetry.lock`) and `click` `^8.1.7` under Poetry, with `tl = "toolong.cli:run"` as the entry point and `textual-dev` in the dev group; there is no test suite and no CI. `src/toolong/ui.py` defines `UI(App)`, which pushes a `LogScreen` whose only binding is `f1` for `action_help`, and the screen composes one `LogView` per file inside a `TabbedContent`. `src/toolong/log_view.py` holds the bindings a user actually reaches for: `ctrl+t` for `action_toggle_tail`, `ctrl+l` for `toggle('show_line_numbers')`, `ctrl+f` and `/` for `action_show_find_dialog`, and `ctrl+g` for `action_goto`. `src/toolong/log_lines.py` adds `m`, `o` and `d` (and their uppercase forms) for `action_navigate` by minute, hour or day, and `src/toolong/help.py` renders the key list as Markdown in a `HelpScreen`.

Textual 0.58 already has the palette; the app just has nothing in it. `App.ENABLE_COMMAND_PALETTE` defaults to `True`, `App.COMMANDS` is a set holding the system commands (toggle dark mode, quit, ring the bell), and the app-level binding `ctrl+backslash` runs `action_command_palette`. A provider is a subclass of `textual.command.Provider` with an `async def search(self, query)` that yields `Hit` objects: a score and a highlighted display from `self.matcher(query).match(name)`, a callable to run, and optional `help` text. An optional `async def discover(self)` yields `DiscoveryHit` rows shown before the user types. The provider sees `self.app`, `self.screen` and `self.focused`, which is how it reaches the active `LogView`.

The agent adds `src/toolong/commands.py` with a `LogCommands(Provider)`. Its command table maps names to the existing actions on the active screen: Toggle tail, Toggle line numbers, Find, Go to line, Help, and Forward and Back one minute, hour and day, each resolved at run time by querying the focused tab's `LogView` and `LogLines` rather than holding a reference, because the screen can switch tabs. `search` runs the fuzzy matcher over the table and yields a `Hit` per match; `discover` yields the same rows so the palette is useful when opened empty. Then `UI.COMMANDS = App.COMMANDS | {LogCommands}` in `ui.py`, which keeps the system commands and adds the app's. The `HELP_MD` string in `help.py` gets one line naming `ctrl+\` so the palette is discoverable from the help the app already has.

There is no test runner in the repository, so the agent adds a minimal `tests/test_commands.py` using pytest and Textual's `App.run_test()` pilot, which exists in 0.58: it starts the app on a temporary log file, presses `ctrl+backslash`, types part of a command name and asserts the palette lists it, then selects it and asserts the `LogView`'s `tail` reactive flipped. `pytest` and `pytest-asyncio` go in the Poetry dev group, and `poetry run pytest` in the sandbox is the output the pull request quotes. The `textual-dev` console can show the same thing by hand, which the description mentions for anyone reviewing on a laptop.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add command palette commands to this Textual app. Read pyproject.toml, poetry.lock, src/toolong/ui.py, log_view.py, log_lines.py, help.py, find_dialog.py and goto_screen.py first, and check the pinned Textual version so you use that version's command palette API. Add src/toolong/commands.py with a Provider subclass whose search method yields a Hit for each matching command and whose discover method lists them all: toggle tail, toggle line numbers, find, go to line, help, and forward and back by one minute, hour and day, each resolved at run time against the LogView in the active tab. Register it by setting UI.COMMANDS to App.COMMANDS plus the new provider so the system commands stay. Add the ctrl+backslash key to the help text. Add a pytest test using App.run_test that opens the palette, searches for the tail command, runs it and asserts the LogView's tail reactive changed, with pytest and pytest-asyncio in the Poetry dev group. Run poetry install and poetry run pytest and open a pull request that quotes the output and lists each command with the action it calls.",
  "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/commands.py` and `tests/test_commands.py`, changes `src/toolong/ui.py` (the `COMMANDS` class variable and an import), `src/toolong/help.py` (one line), and `pyproject.toml` and `poetry.lock` (the two test packages in the dev group). Its description lists each palette command next to the action and binding it mirrors, quotes the `poetry run pytest` output, and names the Textual version the provider was written against.

A reviewer checks that the provider resolves the `LogView` at run time rather than capturing one at construction, so switching tabs in a multi-file session runs the command on the visible file, that the system commands are still present, and that no new binding shadows an existing key. They may want fewer navigation commands in the palette, which is a matter of deleting rows from the table.

After merge, `ctrl+\` opens a searchable list of everything the app can do, each row running the same action a key would, with the keys still working as before.

## Run it on every Dependabot pull request that bumps Textual

The command palette API has moved between Textual releases, so the useful event is a version bump. An automation on the Project with a `github` trigger on `pull_request.opened` filtered to Dependabot's login in `authors` runs on each bump, installs the new version in its sandbox, runs the palette test and posts a review comment with the result and any renamed symbol it found in the release notes. An automation's run is read-only, so it comments and pushes nothing.

When the comment reports a break, a handler on the reader's own server starts the fixing run by sending this body to `POST /o/{org}/sessions` with the pull request URL in `resources` and a `request_id` that is a UUID v5 of the pull request's head commit SHA, so a retried delivery returns the run already started. That run updates the provider for the new API and pushes to the bump branch.

## Why run it on Rush?

The palette API is small but version-bound, and an app with no tests gives no signal when it drifts. The agent reads the pinned version, writes the provider against that API, and adds the first test the repository has, running it in a sandbox where the terminal app can be driven by a pilot and the output is kept with the pull request.

A team with several Textual tools runs the same change on each, and each run reads its own bindings. The provider for a log viewer exposes tailing and time navigation; the one for a different app exposes whatever its screens define, because the agent built the table from the code rather than from a template.

## Frequently asked questions

### Which key opens the palette?

In Textual 0.58 the app-level binding is `ctrl+backslash`, bound to `action_command_palette` with `ENABLE_COMMAND_PALETTE` on by default. The agent adds that key to the help screen so users find it; newer Textual releases may bind a different key, which the version-bump automation would report.

### Do the existing keyboard shortcuts still work?

Yes. The provider calls the same action methods the bindings call, `action_toggle_tail`, `action_show_find_dialog`, `action_goto` and `action_navigate`, so the palette is a second way in rather than a replacement, and no binding is changed.

### Why keep the system commands?

Because `App.COMMANDS` holds Textual's own provider for toggling dark mode, quitting and ringing the bell. Setting `COMMANDS` to a union with the new provider keeps those; replacing the set would silently remove them.

### How is a terminal app tested in CI?

With `App.run_test()`, which runs the app headless and returns a pilot that can press keys and wait for the screen to settle. The test the agent adds presses the palette key, types, selects a command and asserts a reactive attribute changed, all without a real terminal.

## More Textual jobs

- [Add a Config File to a Textual App](https://getrush.ai/run/add-config-file/textual/)
- [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/)

## More jobs like this: Hand off a long task

- [Generate compile_commands.json for a Bazel C++ Project](https://getrush.ai/run/add-compile-commands/bazel/)
- [Add the Mandatory Compliance Webhooks to a Shopify App](https://getrush.ai/run/add-compliance-webhooks/shopify-app/)
- [Refactor a Pulumi Program Into Component Resources](https://getrush.ai/run/add-component-resources/pulumi/)

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