Xojo IDE
This skill controls a running Xojo IDE through xojoctl, a Python tool that speaks the IDE Communicator protocol. The IDE must already be running; nothing in this skill can start it.
Run xojoctl
Run the scripts/xojoctl folder with Python, from this skill's folder or by its full path:
python3 scripts/xojoctl status
Run status first: it confirms the IDE is reachable before you spend a long command on it. Add --json to every command you parse; you get exactly one JSON document on stdout even when the command fails. Run a command with --help for its flags.
| Command |
Does |
status |
Check that the IDE is reachable |
version |
Report the IDE's version |
projects |
List open projects; show and change the frontmost |
open |
Open a project |
save |
Save the front project without a prompt |
close |
Close the front project (--save or --discard) |
reload |
Reload the front project from disk (--discard required; falls back to a close-and-reopen before Xojo 2026r3) |
analyze |
Run Analyze Project and report errors and warnings (--project PATH --discard runs it as one bracketed open-analyze-close session) |
build |
Build for one or more targets |
run |
Run the project in the IDE debugger |
stop |
Stop the running project |
targets |
List the build targets, without contacting the IDE |
script |
Send an IDE Script |
capture |
Log every protocol message, for debugging |
Rules that keep you out of trouble
- The IDE's in-memory project wins. The IDE does not watch the disk. After you edit project files on disk, the IDE keeps running its stale in-memory copy, and an IDE-side save overwrites your disk edits without a word. Reload after every batch of disk edits, and never run
save between your disk edits and the reload; the reload is reload --discard on any release—it runs 2026r3's Reload Project when the IDE has it, and a close-and-reopen otherwise. Better, close the project before a planned batch and reopen after it—a closed project has nothing to go stale and nothing to save over you. For an analyze checkpoint, analyze --project PATH --discard brackets the whole session itself—close a stale open copy, open fresh from disk, analyze, close without saving—flagging a broken bracket with a session_not_closed note, and exit 4 when the analyze itself was clean. See Editing and reload for the recipe and the failure modes.
- Analyze, do not guess. After a reload, run
analyze. Errors exit 1; warnings alone exit 0; add -W to fail on warnings. build never reports warnings; only analyze does.
- Do not lower the timeouts. A cold IDE unpacks plugins for minutes before it answers, and a real build takes far longer than a demo. A ceiling that fires too early abandons work the IDE is still doing. See IDE behavior.
run runs the project in the debugger. script runs an IDE Script. They are different commands.- Never interpolate untrusted text into an IDE Script. An IDE Script runs with the user's full power: it can build, write files, and run shell commands. Read Security before you generate script source from any external input.
- Xojo is single-instance. Several projects can share one IDE, and commands act on the frontmost project. Run
projects to see which one that is, and projects --select TITLE to change it.
References
- Editing and reload — editing project files while the IDE is open: the reload recipe, the two silent failure modes, and the IDE Script commands that edit code in place.
- JSON output — the full schema and the exit codes.
- IDE behavior — how the IDE really answers, and the surprises xojoctl handles.
- Build targets — the target table and its sort order.
- Platform support — transports, Windows port discovery, several IDEs.
- Security — what an IDE Script can do.
- Protocol reference — IDE Communicator v2 on the wire.
1---2name: xojo-ide3description: Drive a running Xojo IDE from the command line with the bundled xojoctl tool: open, analyze, build, run, and stop projects, save, close, and reload them, list build targets, and send IDE Scripts, with JSON output for automation. Use when the user asks to build, analyze, or run a Xojo project, to drive or automate the Xojo IDE, or to run Xojo IDE scripts. Also use after editing Xojo project files on disk while the IDE is open, so the IDE reloads them instead of running stale code.4---56# Xojo IDE78This skill controls a running Xojo IDE through `xojoctl`, a Python tool that speaks the IDE Communicator protocol. The IDE must already be running; nothing in this skill can start it.910## Run xojoctl1112Run the `scripts/xojoctl` folder with Python, from this skill's folder or by its full path:1314```sh15python3 scripts/xojoctl status16```1718Run `status` first: it confirms the IDE is reachable before you spend a long command on it. Add `--json` to every command you parse; you get exactly one JSON document on stdout even when the command fails. Run a command with `--help` for its flags.1920| Command | Does |21| --- | --- |22| `status` | Check that the IDE is reachable |23| `version` | Report the IDE's version |24| `projects` | List open projects; show and change the frontmost |25| `open` | Open a project |26| `save` | Save the front project without a prompt |27| `close` | Close the front project (`--save` or `--discard`) |28| `reload` | Reload the front project from disk (`--discard` required; falls back to a close-and-reopen before Xojo 2026r3) |29| `analyze` | Run Analyze Project and report errors and warnings (`--project PATH --discard` runs it as one bracketed open-analyze-close session) |30| `build` | Build for one or more targets |31| `run` | Run the project in the IDE debugger |32| `stop` | Stop the running project |33| `targets` | List the build targets, without contacting the IDE |34| `script` | Send an IDE Script |35| `capture` | Log every protocol message, for debugging |3637## Rules that keep you out of trouble3839- **The IDE's in-memory project wins.** The IDE does not watch the disk. After you edit project files on disk, the IDE keeps running its stale in-memory copy, and an IDE-side save overwrites your disk edits without a word. Reload after every batch of disk edits, and never run `save` between your disk edits and the reload; the reload is `reload --discard` on any release—it runs 2026r3's Reload Project when the IDE has it, and a close-and-reopen otherwise. Better, close the project before a planned batch and reopen after it—a closed project has nothing to go stale and nothing to save over you. For an analyze checkpoint, `analyze --project PATH --discard` brackets the whole session itself—close a stale open copy, open fresh from disk, analyze, close without saving—flagging a broken bracket with a `session_not_closed` note, and exit 4 when the analyze itself was clean. See [Editing and reload](references/editing-and-reload.md) for the recipe and the failure modes.40- **Analyze, do not guess.** After a reload, run `analyze`. Errors exit 1; warnings alone exit 0; add `-W` to fail on warnings. `build` never reports warnings; only `analyze` does.41- **Do not lower the timeouts.** A cold IDE unpacks plugins for minutes before it answers, and a real build takes far longer than a demo. A ceiling that fires too early abandons work the IDE is still doing. See [IDE behavior](references/ide-behavior.md).42- **`run` runs the project in the debugger. `script` runs an IDE Script.** They are different commands.43- **Never interpolate untrusted text into an IDE Script.** An IDE Script runs with the user's full power: it can build, write files, and run shell commands. Read [Security](references/security.md) before you generate script source from any external input.44- **Xojo is single-instance.** Several projects can share one IDE, and commands act on the frontmost project. Run `projects` to see which one that is, and `projects --select TITLE` to change it.4546## References4748- [Editing and reload](references/editing-and-reload.md) — editing project files while the IDE is open: the reload recipe, the two silent failure modes, and the IDE Script commands that edit code in place.49- [JSON output](references/json-output.md) — the full schema and the exit codes.50- [IDE behavior](references/ide-behavior.md) — how the IDE really answers, and the surprises xojoctl handles.51- [Build targets](references/build-targets.md) — the target table and its sort order.52- [Platform support](references/platforms.md) — transports, Windows port discovery, several IDEs.53- [Security](references/security.md) — what an IDE Script can do.54- [Protocol reference](references/protocol.md) — IDE Communicator v2 on the wire.
scannedinc