Command line✎
Every roswaal command, what it does, and which of them keep running.
Pending review
roswaal is shaped after rojo's command line on purpose: it sits beside Rojo in the same workflow, and a tool that invents its own conventions makes you learn twice. Run it in the project directory, or point it at one with --root.
sh
roswaal new my-game # a new project, in a new folder cd my-game # or, in a project you have: roswaal init, once roswaal serve # editor on http://127.0.0.1:4471, docs at /docs
Commands
| Command | What it does |
|---|---|
roswaal new | Make a new project in an empty folder: roswaal new <folder>. Writes roswaal.json, a node map that writes default.project.json with Rojo's three folders (Server in ServerScriptService, Client in StarterPlayerScripts, Shared in ReplicatedStorage), a Main graph that prints Hello world, and place.rbxl: a baseplate, a spawn and the usual services, for roswaal export to write scripts into. Then compiles it. --lune makes a Lune project instead, with one main graph and no place. A folder that already has files in it is refused: roswaal init sets one of those up. |
roswaal init | Create roswaal.json and .roswaal/ in this project. Like rojo init. Writes roswaal.json, the graph and node-pack directories, and a commented example pack. Anything already there is kept rather than overwritten. |
roswaal import | Make a project from a place file, or a node map from a Rojo project file. roswaal import <place.rbxl> [directory] reads .rbxl and .rbxlx. Scripts Rojo can sync go under src/ with a default.project.json that leaves everything else in the place alone. --scripts all also brings in scripts inside parts and models, under place/; identical ones become one file unless you pass --no-merge. The place is copied into the new project. roswaal import default.project.json reads a Rojo project into a node map beside it, and Roswaal writes the file from then on when the map says the same thing. |
roswaal export | Write the project's place, holding its scripts, to a file: roswaal export <place.rbxl>. Every script the project has a file for is written into a copy of its place, and one not in the place yet is added, with the folders it needs. Nothing else in the place changes, and the project's own place file is left as it was unless you name it. |
roswaal serve | Start the daemon and serve the editor. Blocks. The editor at http://127.0.0.1:4471, the documentation at /docs, and — when Compile is set to Dynamic — a watcher recompiling graphs as they change. |
roswaal stop | Stop a running daemon on this port. Over HTTP rather than a PID file, and it reports success only once the daemon has actually gone quiet. |
roswaal restart | Stop a running daemon, then serve again. What to run after rebuilding: serve loads the CLI bundle once, so a rebuild does not reach a daemon that is already up. |
roswaal status | Is a daemon running here, and what is it serving? |
roswaal compile | Compile every graph and map once and exit. Takes an optional path. One path compiles one document. A generated file somebody has edited by hand is refused rather than overwritten — pass --force to take it back. |
roswaal watch | Recompile graphs as they change, without the editor. Blocks. The same compile the editor runs, for working in a text editor beside Rojo. |
roswaal prune | Remove generated files whose graph has moved or gone. Lists what it would delete and stops. --yes is you saying you have read the list. |
roswaal check | One-shot health probe. Plain output, good for scripts. Aligned key: value lines, no colour and no box: this is the one a script reads. |
roswaal version | Print the version and exit. The number alone, for a script that needs to know which build it is talking to. |
roswaal help | This list. Add --help to any command to describe that one. |
Info
serve, watch and restart block until Ctrl+C. Everything else exits when done, so check and compile suit scripts.Options
| Option | What it does |
|---|---|
--root <path> | Project directory. Default: the current directory. |
--port <n> | HTTP port for the daemon. Default: 4471. |
--force | For compile: overwrite generated files edited by hand. |
--merge | For compile: move a folder whose map path changed into a new folder that already has files. |
--no-open | For serve: do not print the editor URL as a hint. |
--yes | For prune: delete the files it lists, rather than only listing them. |
--scripts <rojo|all> | For import: only scripts Rojo can sync (default), or all of them. |
--no-merge | For import: keep identical scripts as separate files. |
--lune | For new: a Lune project rather than a Roblox one. |
--no-place | For new: leave out place.rbxl. |
--help, -h | Describe the command it follows, without running it. |
--version | Print the version and exit. |
Two things worth knowing
Warning
Restart the daemon after rebuilding Roswaal. A reload picks up the new editor, but the server keeps running the old code.
stop and restart reach the daemon over HTTP rather than through a PID file, so there is no stale pid to reason about when one dies unexpectedly. stop reports success only once the health probe has gone quiet — not when the request was sent.
Not reviewed yet