# How to run uv commands from the editor

This guide shows how to format, lint, build, test and run your project without leaving Turbo Python. It assumes the editor is installed and you have a Python project.

## Get a starter file

Start the editor **from the project's own directory**, then choose **Python ▸ Create tools file** (`Alt-P`, then `C`).

That writes `.turbo-python/tools.toml` with the five commands a Python project runs before it commits, and opens it:

```toml
[[tool]]
name = "~F~ormat"
command = "uv run ruff format ."
output = "popup"

[[tool]]
name = "~T~est"
command = "uv run pytest"
output = "popup"

[[tool]]
name = "~R~un"
command = "uv run"
# A terminal, not a popup: a program that reads the keyboard has to be able to
# be answered, and one that runs long has to be able to be interrupted.
output = "terminal"
```

Each `[[tool]]` becomes one line of the **Python** menu, in the order they appear — unless it names a `menu` of its own, which the next-but-one section covers. The file is read every time the menu opens, so an edit takes effect immediately.

## Run one

`Alt-P`, then the letter between the tildes — `F` to format, `T` to test.

A **popup** opens at once and fills in as the command runs. Its title carries the command and, once it has ended, how it went:

```
┌──────────── uv run ruff check . — exit 1 ────────────┐
│  main.py:6:2: unreachable code                │
│                                               │
│                   [ Close ]                   │
└───────────────────────────────────────────────┘
```

| Key | Effect |
| --- | --- |
| `↑` `↓` `PgUp` `PgDn` `Home` `End` | Read through the output |
| `Escape` | Close it — and **stop the command** if it is still running |
| `Enter` | Close it |

A command that succeeded silently shows `(no output)` rather than a blank box, so you can tell it from one that has not started.

The popup follows the output as it arrives until you scroll back, and then leaves you where you are.

## Choose where the output goes

Set `output` on a tool:

| `output` | What you get |
| --- | --- |
| `popup` | A dialog that fills in as it runs. The default. |
| `terminal` | A terminal window: colours, `Ctrl-C`, and the keyboard reaches the program |
| `editor` | An editing window once it has finished, to search with `Ctrl-F` |

`Run` is `terminal` in the starter file, and it is the example of why the key exists: a popup cannot answer a program that reads from the keyboard, and cannot be interrupted with `Ctrl-C`.

Reach for `editor` when the output is something to work through — a long `go test -v`, or a coverage report you want to search.

## A long command holds the editor

A popup is modal: while `go build` runs, you cannot type anywhere else. `Escape` closes it and stops the command.

If that gets in the way for a particular command, give it `output = "terminal"` — the window is an ordinary one and you can carry on working beside it. That is what making the key configurable is for.

## What happens to your open files

`Format` rewrites files on disk — including the one you are looking at. When a command finishes, the editor **re-reads every open file that has no unsaved changes**, so the formatted version appears without you doing anything. The status bar says how many.

A file with unsaved changes is **left alone**, and the status bar says so too:

```
Reloaded 2 files; 1 file with unsaved changes left alone
```

That is deliberate: your edit and the formatter genuinely disagree, and the editor is not the one that should decide which wins. Save first (`F2`) and run the command again, or keep editing and format later.

## Add your own commands

Edit `.turbo-python/tools.toml`. A command goes to `sh -c`, so one entry can be a whole sequence:

```toml
[[tool]]
name = "~C~heck"
command = "uv run ruff format . && uv run ruff check . && uv run pytest"
output = "popup"

[[tool]]
name = "~U~pgrade"
command = "uv lock --upgrade"
output = "popup"

[[tool]]
name = "Cover~a~ge"
command = "uv run pytest --cov --cov-report=term-missing"
output = "editor"
```

Give each a hot key with tildes, and keep them distinct — the menu answers the first match it finds.

## Put a tool in a menu of its own

A tool that has nothing to do with Python does not belong in the Python menu. Give it a `menu`:

```toml
[[tool]]
name = "~E~cho"
command = "echo TADA"
output = "terminal"
menu = "Tools"

[[tool]]
name = "~U~p"
command = "docker compose up -d"
menu = "Docker"

[[tool]]
name = "~D~own"
command = "docker compose down"
menu = "Docker"
```

That gives you a **Tools** menu and a **Docker** menu on the bar, between Python and Help, in the order the names first appear in the file. Docker holds both its tools. Nothing needs restarting: save the file and the bar follows.

The name is yours to choose — there is no list to pick from. Leave `menu` out and the tool stays in Python, which is where all five starter commands are.

### The hot key is chosen for you

You cannot know, when writing the file, which letters the editor's own menus have taken. So it works it out: the first letter of the name that nothing else claims gets the tildes.

`Tools` gets `Alt-T`, because `T` is free. A menu called `Format` would get `Alt-A`, because `F` is File's, `o` is Options' and `r` is Run's.

Write the tildes yourself — `menu = "Doc~k~er"` — and a free letter is kept. A taken one is not: the bar answers the *first* menu matching a key, so honouring your choice would make one of the two menus unreachable. It picks another letter and says nothing.

## Variants

- **You want `black` and `flake8` instead of `ruff`.** Change the `Format` and `Lint` commands. `ruff` is the default because it is one tool for both jobs and `uv run` fetches it on demand; anything else is equally one line.
- **You started the editor from a subdirectory.** Commands run there, so `ruff check .` covers only that subtree — and `uv` looks for the `pyproject.toml` from there too. Start from the project root.
- **The file has a mistake in it.** The menu shows a greyed-out `Cannot read tools` where the commands would be, and **Create tools file** is still there.
- **A command is not installed.** The popup shows `command not found` and `— exit 127`, which is what a shell would have said.
- **You want a menu named after one that exists.** `menu = "File"` gives you a second File menu, further along the bar, with a different hot key. Nothing stops you; nothing recommends it either.
- **Your menu has no hot key.** Every letter in its name was already taken. `F10` and the arrow keys reach it, and so does the mouse. Rename it to something with a free letter.
- **You misspelt `output`'s value.** The whole file is refused and the menu says `Cannot read tools`, naming the tool and listing what it could have been. A silent fallback would have sent the output somewhere you did not ask for.

## Ask for a value when the command runs

Some commands need something typed each time: a module path, a project name, a test to filter on. Put a `{{label}}` where the value goes:

```toml
[[tool]]
name = "~I~nit module"
command = "uv init --app {{project name}}"
output = "popup"
```

Choosing it now opens a box titled **Init module** with one field, labelled `module path`. Type the value and press Enter; the command runs with it. Escape, and nothing runs.

The value is quoted, so a path with a space in it stays one argument.

### Several values at once

One field each, in the order they appear:

```toml
[[tool]]
name = "~C~opy"
command = "cp {{from}} {{to}}"
```

**Tab** moves between the fields, **Enter** runs it.

### One field standing for several arguments

Quoting is wrong when you mean "put these flags on the end". Add `...` inside the braces and the value goes in verbatim:

```toml
[[tool]]
name = "Test ~o~ne"
command = "uv run pytest {{extra flags...}}"
```

Type `--release parse` and all of it reaches the command as separate arguments.

### The same value twice

Write the label twice; you are asked once:

```toml
[[tool]]
name = "~N~ew directory"
command = "mkdir {{name}} && cd {{name}}"
```

### Variants

- **The value is the same most times.** Run it once and the box remembers what you typed, for the rest of the session. It is not written to disk.
- **Your command has braces in it already.** `awk '{print $1}'` and `find . -exec rm {} +` are left alone: only double braces ask for anything.
- **The command asks for more values than fit on screen.** The editor says so rather than opening a box whose OK button is below the bottom of the terminal. Make the terminal taller, or split the command into two tools.

## See also

- Every key of the file and every rule: [Python tools reference](../reference/python-tools.md)
- Why each command gets a terminal window, and why an unmodified file reloads: [Python tools](../explanation/python-tools.md)
- The windows the commands run in: [Terminal windows](../reference/terminal.md)