# Reference: command line

> Neutral description of the `turbo-python` command, its flags, and the environment it reads.

## Synopsis

```
turbo-python [flags] [file...]
```

Each `file` is opened in its own window. A file that does not exist yet is opened as an empty buffer bound to that path. With no file at all, one empty untitled window is opened.

## Flags

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `-theme <name>` | string | the project's, else `turbo-classic` | Theme to start with, overriding the project's own. An unknown name falls back to the default without an error. |
| `-list-themes` | bool | `false` | Print every loadable theme with its description, then the user theme directory, and exit. |
| `-no-lsp` | bool | `false` | Do not start a language server. Colouring and editing are unaffected. |
| `-version` | bool | `false` | Print `Turbo Python <version>` on one line, with the commit and build date when the build recorded them, and exit. See [the version number](versioning.md). |
| `-h`, `-help` | bool | `false` | Print the flag list and exit. |

## Environment

| Variable | Read by | Effect |
| --- | --- | --- |
| `TURBO_PYTHON_THEME_DIR` | theme loading | Directory to read user themes from, instead of the platform configuration directory. |
| `TERM` | tcell | Which terminal description to use. |
| `GOBIN`, `GOPATH`, `HOME` | pylsp lookup | Searched, in that order, when `pylsp` is not on `PATH`. |

## Files

| Path | Purpose |
| --- | --- |
| `$TURBO_PYTHON_THEME_DIR/*.toml` | User themes, when the variable is set. |
| `./.turbo-python/settings.toml` | This project's settings, read once at start-up. See [project settings](project-settings.md). |
| `~/.config/turbo-python/themes/*.toml` | User themes on Linux (`os.UserConfigDir`). |
| `~/Library/Application Support/turbo-python/themes/*.toml` | User themes on macOS. |
| `<module>/pyproject.toml` | Located by walking up from the first file; its directory becomes the language server's root. |

## Exit status

| Status | Meaning |
| --- | --- |
| `0` | The editor exited normally, or an informational flag was used. |
| `1` | The terminal could not be opened or initialised. The reason is printed to standard error. |

## Make targets

Run from a checkout.

| Target | What it runs |
| --- | --- |
| `make help` | List the targets. This is the default. |
| `make test` | `uv run pytest` |
| `make test-verbose` | `go test -v ./...` |
| `make cover` | `go test -cover ./...` |
| `make build` | `go build -o bin/turbo-python .` |
| `make install` | `scripts/install.sh` — build and install onto your PATH |
| `make uninstall` | `scripts/install.sh --uninstall` |
| `make run FILE=x.go` | `make build`, then `./bin/turbo-python x.go` |
| `make fmt` | `go fmt ./...` |
| `make vet` | `uv run ruff check .` |
| `make check` | `fmt`, then `vet`, then `test` |
| `make clean` | Remove `bin/` |

## Examples

```bash
turbo-python                              # one empty window
turbo-python main.py pyproject.toml               # two windows
turbo-python -theme turbo-dark main.py    # a different theme
turbo-python -no-lsp main.py              # no language server
turbo-python -list-themes                 # what themes exist
```

## Installer

`scripts/install.sh`, also reachable as `make install`.

| Option | Description |
| --- | --- |
| `-p`, `--prefix DIR` | Install into `DIR` instead of `$GOBIN` or `$GOPATH/bin`. |
| `--with-pylsp` | Install `pylsp` as well, if it is not already there. |
| `--uninstall` | Remove an installed `turbo-python` and stop. |
| `-h`, `--help` | Print the options and stop. |

| Exit status | Meaning |
| --- | --- |
| `0` | Installed, removed, or help printed. |
| `1` | Go missing or too old, the build failed, or the destination could not be written. Nothing is installed and an existing installation is left untouched. |

## Errors

| Message | Cause |
| --- | --- |
| `turbo-python: opening the terminal: …` | tcell could not open the terminal; usually `TERM` is unset or unknown. |
| `turbo-python: initialising the terminal: …` | The terminal was opened but could not be put into raw mode. |
| `Cannot open` (in a dialog) | The path is a directory, or is not readable. |
| `Cannot save` (in a dialog) | The directory does not exist, or is not writable. |