Hey all! I created a CLI tool for starting new roc apps. This tool allows you to specify the platform and packages you want to use, and roc-start
will generate a .roc
file for you with the latest releases of the packages and platforms you specified.
Lots of room for improvement, like possibly using Hasnep/roc-packages for the backend, generating package headers as well as apps, or allowing specifying a specific version of a platform or package, but I think its already pretty useful as is.
There are two workflows:
Include the application name, platform, and packages as CLI args:
roc-start my-app basic-cli weaver json
Provide or edit a configuration file:
roc-start config -d
config
allows you to specify a pre-existing config file, or launch an editor to edit a template configurationI'm embarrassed to say that having used Roc for over a year I still have to copy and paste an app header from another project every single time :sweat_smile: This will be very useful!
Haha, yep! Right there with ya… :sweat_smile: I finally got fed up!
Ha, it looks very similar to the concept @Luke Boswell proposed here: https://roc.zulipchat.com/#narrow/stream/304641-ideas/topic/roc.20init.20app.20scaffolding
I'm very happy to see this exist :heart: . It will make it so much easier to get started with new apps.
As a tool I think this will be much easier for us to upgrade and innovate. I'm guessing long term we will still want it integrated for a "batteries included" experience??
One of the ideas I was proposing is that platform authors can provide a plugin or script to scaffold out an app structure. I figured it could support more complicated things than a single main.roc
file which may be helpful, but I'm not sure about.
I'd be interested to know @Ian McLerran if you have any thoughts?
Wow, yeah, thanks for calling this out @Kiryl Dziamura… my CLI app here is definitely a rudimentary implementation of the roc init
proposal. @Luke Boswell, I really like the design you have proposed for how the cli app could function.
A few thoughts:
1) The init.roc script solves a major shortcoming of my roc-start
tool - namely the ability generate any code after the header. Since each platform can have a different API, roc-start doesn’t even attempt to generate the interface for the platform, let alone any other files. It also provides a way for the platform to have its own opinion on what its alias should be, rather than having to store that info in the repository, which is what roc-start does.
2) roc start
provides one functionality not currently included in the roc init
proposal. This of course is fetching package urls and including them in code gen in addition to the platform. I really like this functionality, but the tradeoff for more complete code gen targeting the platform may be worth it. It would also not be prohibitive for roc init
to insert package urls into the code generated by the init.roc script. The issue of an alias for each package would still need to be solved though.
3) The proposal for roc init
takes a fairly different approach to project initialization from roc-start
, but I am totally down to adapt my project to follow the proposed design. Sounds like a fun project!
I really like the addition of packages. It would be cool to include that in the roc init
design somehow.
Coming soon [TM]... :grinning_face_with_smiling_eyes:
Screenshot-2024-06-03-at-09.18.22.png
Okay, TUI app is live! Use with: roc-start tui
New features:
Deprecated:
Quick note: I introduced a bug around 9pm CDT last night which shows blank input options in the bottom-bar by pushing to main when I should have been on a feature branch. Should have the fix live in the next hour... :rolling_eyes::sweat_smile:
Okay, bugs should be resolved. Shouldn't impact functionality, but I'd recommend making sure you're on roc-start --version
>= v0.2.1 for the best experience.
Lesson learnt: enable main branch protection on all my repos! :sweat_smile:
Haha yeah no kidding!
A couple updates to roc-start:
1) Now correctly generates headers for platforms which require something besides just “main”, IE kingfisher requires [main, Model]
.
2) Scaffolds a basic app for 3/4 platforms currently listed (using “app stubs”).
To get these updates, make sure you have roc-start v0.3.3
. If you have app stubs (v0.3.0+), but not the kingfisher stub, run with the -u
flag. Starting with v0.3.4
you can also run roc-start update -s
to update the app stubs, without requiring other valid command line args (tui
or appName
platform
).
Three new packages available from roc-start
:
To get the latest packages, run roc-start update --packages
(on roc-start v0.3.4+), or roc-start -u tui
, on any* version.
I'm having trouble using roc-start.
I cloned the repository. Built the app using roc build src/main.roc --output roc-start
. Sym-linked it into /usr/local/bin
. I can run roc-start update
which gives me three green ticks for updating its repositories.
But, when I go to use the app I have Nil repositories loaded.
11:22:48 ~/Documents/GitHub/roc pr6733 $ roc-start update
Updating platform repository... ✔
Updating package repository... ✔
Updating app-stubs... ✔
Screenshot-2024-06-28-at-11.24.01.png
Am I missing something?
What’s the output for ls -la ~/.roc-start
?
$ ls -al ~/.roc-start
total 16
drwxr-xr-x 5 luke staff 160 28 Jun 11:19 .
drwxr-x---+ 90 luke staff 2880 29 Jun 08:37 ..
drwxr-xr-x 2 luke staff 64 28 Jun 11:19 app-stubs
-rw-r--r-- 1 luke staff 3 28 Jun 11:25 pf-data.rvn
-rw-r--r-- 1 luke staff 3 28 Jun 11:25 pkg-data.rvn
$ cat ~/.roc-start/pkg-data.rvn
[
]
And pf-data.rvn
? That is offending screenshot referring to
oh 3 bytes, nvm ^^
Hmm… what about roc-start —version
I thought I had kept my changes to the repo non-breaking for older versions of the app, but that would be my next question…
Okay, looks like I need to handle network failures when downloading updates. If the network fails, you’ll end up with empty rvn files. I’m not able to do much over the weekend here to fix that, but is there any chance that you didn’t have internet access when running roc-start update
?
Sunday I’ll try to get out an update which lets you know if updates fail, and avoid overwriting an existing cache if that happens.
$ roc-start -V
v0.3.4
I DM'd you copies of the .rvn
files just as a quick fix.
I can run the update now and it is still empty
Do you have the github cli installed and authenticated?
I think so. Like this?
$ git --version
git version 2.45.2
I just did
$ brew install gh
[removed this bit of homebrew installing gh]
13:00:16 ~/.roc-start $ roc-start update
Updating platform repository... ✔
Updating package repository... ✔
Updating app-stubs... ✔
And now my rvn files are empty again
ahh, now just do gh auth login
Ohk, that was the issue. Now it's working fine
I definitely missed this part of the README
Please make sure to install and log into
gh
before runningroc-start
.
I've never used gh
before
The install.sh
script currently checks for the gh cli, but roc-start itself really should be notifying you of these errors. I'll try to get that pushed out here soon.
I also hadn't noticed the install.sh
script. :sweat_smile:
Well to be fair roc-start really shouldn't be giving you :check:s for your update when its totally failing! :sweat_smile:
How do I create a basic-cli app without any packages?
$ roc-start app basic-cli
Error: The 'platform' parameter did not receive a value.
Usage:
roc-start app [options] <app-name> <platform> <packages...>
I've tried a few different things and haven't figure it out yet.
Lol, figured it out -- missing a name for the app
$ roc-start app test basic-cli
Created test.roc ✔
I've got a fix for the "successful failures" issue when running roc-start update
now. Fixes are live, and should give helpful error messages for most failure modes, and always let you know if the update failed.
Coming soon to a terminal near you!
$ roc-start app --platform basic-cli:latest \
rtils:0.1.0 roc-ansi imclerran/roc-tinyparse:latest \
roc-semver json roc-heck:0.1.1
Creating main.roc...
Platform: roc-lang/basic-cli : 0.19.0
Packages
| imclerran/rtils : v0.1.0
| lukewilliamboswell/roc-ansi : 0.8.0
| imclerran/roc-tinyparse : v0.3.3
| roc-semver : ambiguous; use <owner>/roc-semver - skipping
| json : package repo not found; did you mean roc-json? - skipping
| roc-heck : version not found; latest is v0.1.0 - skipping
Created main.roc with 3 packages and skipped 3 packages ✔
Screenshot 2025-02-25 at 16.37.51.png
New roc-start
experience is getting close!
Screenshot 2025-03-03 at 14.09.32.png
Very happy to say the new roc-start
cli tool is finally ready for prime time! This was a full rewrite of the core functionality of the app, and very little was untouched of the 4925 lines of code (although when I have more time, the TUI itself really deserves a ground-up rewrite).
A ton of new features, as mentioned in the screenshot above, but my main goals were the following:
Hope ya'll find this useful! Let me know if you have any questions, encounter any bugs, or have suggestions for improvement!
cli-usage.png
tui-main-menu.png
https://github.com/imclerran/roc-start
In addition to minor bug fixes and UI improvements, a couple feature updates since 0.6.0:
$HOME/.rocstartthemes
--force
in the TUIRoc-start can now install its own updates! (Assuming you have a global install of roc)
Starting with roc-start v0.7.3, just do roc-start update --install
.
Last updated: Jul 06 2025 at 12:14 UTC