# How to run Golo commands from the editor

This guide shows how to run, test, debug and compile your scripts without leaving Turbo Golo. It assumes the editor is installed and you have a directory with a `.golo` file in it.

## Get a starter file

Start the editor **from the directory your scripts live in**, then choose **Golo ▸ Create tools file** (`Alt-G`, then `C`).

That writes `.turbo-golo/tools.toml` with the commands a Golo programmer runs most, and opens it. The first three:

```toml
[[tool]]
name = "~R~un"
# The interpreter, on the file you name. A terminal, not a popup: a script that
# reads the keyboard has to be able to be answered, and one that runs long has
# to be able to be interrupted.
command = "golo {{script, e.g. main.golo}}"
output = "terminal"

[[tool]]
name = "~T~est"
# Every *_test.golo under the current directory, with gololang.Testing.
command = "golo --test"
output = "popup"

[[tool]]
name = "Test ~o~ne"
command = "golo --test {{test file or directory}}"
output = "popup"
```

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

## Run one

`Alt-G`, then the letter between the tildes — `R` to run, `T` to test.

**Run** asks first, because Golo has no manifest that says which file is the program:

```
┌──────────────── Run ────────────────┐
│  script, e.g. main.golo             │
│  [                               ]  │
└─────────────────────────────────────┘
```

Type `main.golo` and press `Enter`. A terminal window opens and the script runs in it; when it ends the window stays, showing what it printed. Press `Ctrl-W` to close it. Run it again and the box remembers the name for the rest of the session.

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

```
┌──────────────── golo --test — ok ─────────────────┐
│  🧪 Running Golo tests...                          │
│                                                    │
│  📝 shapes_test.golo                               │
│    ✓ a point describes itself                      │
│    ✅ 1 test(s) passed                             │
│                                                    │
│                     [ 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 rest of the menu

| Item | What it runs | Where |
| --- | --- | --- |
| **Debug** | `golo --debug <script>` — the interpreter with its step debugger on | a terminal, because the debugger reads the keyboard |
| **REPL** | `golo` — the read-eval-print loop | a terminal |
| **New script** | `golo new main --module <name> --name <file>` — a starter program from GoloScript's own template | a popup; the new file appears in the project tree |
| **Build native** | `gogolo build -o <out> <script>` — Golo → Go → a native executable | a popup; needs the Go toolchain |
| **Build wasm** | `wagolo build -target=<wasi\|js\|wasip2> -o <out.wasm> <script>` — Golo → Go → TinyGo → WebAssembly | a popup; needs TinyGo, and `wasm-tools` for `wasip2` |

`Build native` can take a while: it runs the Go compiler. The popup is modal, so while it runs you cannot type anywhere else; `Escape` closes it and stops the compile.

## 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`, `Debug` and `REPL` are `terminal` in the starter file, and they are the example of why the key exists: a popup cannot answer a script that calls `readln`, cannot be interrupted with `Ctrl-C` while `httpServe` is listening, and cannot be a REPL at all.

Reach for `editor` when the output is something to work through — the Go source that `gogolo transpile main.golo` prints, or a long test report you want to search.

## A long command holds the editor

A popup is modal: while `gogolo 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

Golo has no formatter, so nothing in the starter file rewrites the file you are looking at. But `New script` writes a new file into the directory, `gogolo build -keep-go` leaves a `.go` beside your script, and a tool of your own may do anything. When a command finishes, the editor **re-reads every open file that has no unsaved changes**, so a file another command changed appears as it now is, and the project tree is refreshed so a new one shows up. 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 command 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.

## Add your own commands

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

```toml
[[tool]]
name = "Test and ~b~uild"
command = "golo --test && gogolo build -o bin/app main.golo"
output = "popup"

[[tool]]
name = "~T~ranspile"
command = "gogolo transpile {{script, e.g. main.golo}}"
output = "editor"

[[tool]]
name = "Run in ~D~ocker"
command = "docker run --rm -v \"$PWD:/app\" -w /app k33g/gololang:latest /golo ./{{script}}"
output = "terminal"
```

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 Golo does not belong in the Golo 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 Golo 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 Golo, which is where eight of the nine 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. A menu called `Go` would get `Alt-O`… no — `O` is Options'; it would get no hot key at all, because `G` is Golo's, and `F10` would be the way to it.

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 have one script and never another.** Replace `golo {{script, e.g. main.golo}}` with `golo main.golo`, and the box stops appearing. The placeholder is there because a starter file cannot know which file is the program.
- **You started the editor from a subdirectory.** Commands run there, and relative paths in the box are relative to it. Start from the directory the scripts are in.
- **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.
- **`gogolo` or `wagolo` is not installed.** The popup shows `command not found` and `— exit 127`, which is what a shell would have said. GoloScript's `install.sh` installs all three binaries together; a release download is one binary at a time.
- **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

Six of the starter commands already do. The pattern is a `{{label}}` where the value goes:

```toml
[[tool]]
name = "~N~ew script"
command = "golo new main --module {{module name, e.g. hello.World}} --name {{file name without .golo}}"
output = "popup"
```

Choosing it opens a box titled **New script** with two fields, one per placeholder, in the order they appear. **Tab** moves between them, **Enter** runs the command. Escape, and nothing runs.

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

### One field standing for several arguments

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

```toml
[[tool]]
name = "Run with ~a~rguments"
command = "golo main.golo {{arguments...}}"
output = "terminal"
```

Type `--verbose input.txt` and both reach the script as separate arguments — `args` in `function main = |args|` holds them.

### The same value twice

Write the label twice; you are asked once:

```toml
[[tool]]
name = "~C~ompile and run"
command = "gogolo build -o /tmp/app {{script}} && /tmp/app"
```

### 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: [Golo tools reference](../reference/golo-tools.md)
- Why Run comes first, and why an unmodified file reloads: [Golo tools](../explanation/golo-tools.md)
- The windows the commands run in: [Terminal windows](../reference/terminal.md)