| 📦 Turbo Python 6fc62ea k33g yesterday | 1 | # Reference: command line |
| 2 | |
| 3 | > Neutral description of the `turbo-python` command, its flags, and the environment it reads. |
| 4 | |
| 5 | ## Synopsis |
| 6 | |
| 7 | ``` |
| 8 | turbo-python [flags] [file...] |
| 9 | ``` |
| 10 | |
| 11 | 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. |
| 12 | |
| 13 | ## Flags |
| 14 | |
| 15 | | Flag | Type | Default | Description | |
| 16 | | --- | --- | --- | --- | |
| 17 | | `-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. | |
| 18 | | `-list-themes` | bool | `false` | Print every loadable theme with its description, then the user theme directory, and exit. | |
| 19 | | `-no-lsp` | bool | `false` | Do not start a language server. Colouring and editing are unaffected. | |
| 20 | | `-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). | |
| 📦 Turbo Python 8d00593 k33g 8h ago | 21 | | `-load-config <url>` | string | none | Copy the `.turbo-python` directory found at a repository URL — rickub, GitHub, GitLab or Codeberg, the URL of the directory as the browser shows it — into the working directory, print what arrived, and exit. Needs `git`. Refuses when `./.turbo-python` already exists. The editor is not started. | |
| 📦 Turbo Python 6fc62ea k33g yesterday | 22 | | `-h`, `-help` | bool | `false` | Print the flag list and exit. | |
| 23 | |
| 24 | ## Environment |
| 25 | |
| 26 | | Variable | Read by | Effect | |
| 27 | | --- | --- | --- | |
| 28 | | `TURBO_PYTHON_THEME_DIR` | theme loading | Directory to read user themes from, instead of the platform configuration directory. | |
| 29 | | `TERM` | tcell | Which terminal description to use. | |
| 30 | | `GOBIN`, `GOPATH`, `HOME` | pylsp lookup | Searched, in that order, when `pylsp` is not on `PATH`. | |
| 31 | |
| 32 | ## Files |
| 33 | |
| 34 | | Path | Purpose | |
| 35 | | --- | --- | |
| 36 | | `$TURBO_PYTHON_THEME_DIR/*.toml` | User themes, when the variable is set. | |
| 37 | | `./.turbo-python/settings.toml` | This project's settings, read once at start-up. See [project settings](project-settings.md). | |
| 📦 Turbo Python 8d00593 k33g 8h ago | 38 | | `./.turbo-python/` (written) | Created by `-load-config` from a repository's copy, when the project has none yet. | |
| 📦 Turbo Python 6fc62ea k33g yesterday | 39 | | `~/.config/turbo-python/themes/*.toml` | User themes on Linux (`os.UserConfigDir`). | |
| 40 | | `~/Library/Application Support/turbo-python/themes/*.toml` | User themes on macOS. | |
| 41 | | `<module>/pyproject.toml` | Located by walking up from the first file; its directory becomes the language server's root. | |
| 42 | |
| 43 | ## Exit status |
| 44 | |
| 45 | | Status | Meaning | |
| 46 | | --- | --- | |
| 47 | | `0` | The editor exited normally, or an informational flag was used. | |
| 48 | | `1` | The terminal could not be opened or initialised. The reason is printed to standard error. | |
| 49 | |
| 50 | ## Make targets |
| 51 | |
| 52 | Run from a checkout. |
| 53 | |
| 54 | | Target | What it runs | |
| 55 | | --- | --- | |
| 56 | | `make help` | List the targets. This is the default. | |
| 57 | | `make test` | `uv run pytest` | |
| 58 | | `make test-verbose` | `go test -v ./...` | |
| 59 | | `make cover` | `go test -cover ./...` | |
| 60 | | `make build` | `go build -o bin/turbo-python .` | |
| 61 | | `make install` | `scripts/install.sh` — build and install onto your PATH | |
| 62 | | `make uninstall` | `scripts/install.sh --uninstall` | |
| 63 | | `make run FILE=x.go` | `make build`, then `./bin/turbo-python x.go` | |
| 64 | | `make fmt` | `go fmt ./...` | |
| 65 | | `make vet` | `uv run ruff check .` | |
| 66 | | `make check` | `fmt`, then `vet`, then `test` | |
| 67 | | `make clean` | Remove `bin/` | |
| 68 | |
| 69 | ## Examples |
| 70 | |
| 71 | ```bash |
| 72 | turbo-python # one empty window |
| 73 | turbo-python main.py pyproject.toml # two windows |
| 74 | turbo-python -theme turbo-dark main.py # a different theme |
| 75 | turbo-python -no-lsp main.py # no language server |
| 76 | turbo-python -list-themes # what themes exist |
| 📦 Turbo Python 8d00593 k33g 8h ago | 77 | turbo-python -load-config https://rickub.com/turbo-editors/configs/tree/main/golang-init # start from a shared configuration |
| 📦 Turbo Python 6fc62ea k33g yesterday | 78 | ``` |
| 79 | |
| 80 | ## Installer |
| 81 | |
| 82 | `scripts/install.sh`, also reachable as `make install`. |
| 83 | |
| 84 | | Option | Description | |
| 85 | | --- | --- | |
| 86 | | `-p`, `--prefix DIR` | Install into `DIR` instead of `$GOBIN` or `$GOPATH/bin`. | |
| 87 | | `--with-pylsp` | Install `pylsp` as well, if it is not already there. | |
| 88 | | `--uninstall` | Remove an installed `turbo-python` and stop. | |
| 89 | | `-h`, `--help` | Print the options and stop. | |
| 90 | |
| 91 | | Exit status | Meaning | |
| 92 | | --- | --- | |
| 93 | | `0` | Installed, removed, or help printed. | |
| 94 | | `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. | |
| 95 | |
| 96 | ## Errors |
| 97 | |
| 98 | | Message | Cause | |
| 99 | | --- | --- | |
| 100 | | `turbo-python: opening the terminal: …` | tcell could not open the terminal; usually `TERM` is unset or unknown. | |
| 101 | | `turbo-python: initialising the terminal: …` | The terminal was opened but could not be put into raw mode. | |
| 102 | | `Cannot open` (in a dialog) | The path is a directory, or is not readable. | |
| 103 | | `Cannot save` (in a dialog) | The directory does not exist, or is not writable. | |
| 📦 Turbo Python 8d00593 k33g 8h ago | 104 | | `turbo-python: configrepo: the project already has a configuration directory: …` | `-load-config` into a project that already has `.turbo-python`. Move it away first. | |
| 105 | | `turbo-python: configrepo: git is not installed` | `-load-config` needs the `git` command on `PATH`. | |
| 106 | | `turbo-python: configrepo: no configuration directory at that path: …` | The repository was found but holds no `.turbo-python` where the URL points. | |
| 107 | | `turbo-python: configrepo: no repository answered: …` | No clone address for that URL answered; the URL, the network, or a private repository. | |