star

Quick start

in progress

A quick tour of star’s orbit: first run, scaffolding a project, and authoring a template.

First run

There is no star init. Run any command that needs configuration and star creates the global config (star.config.toml) for you, interactively offering to include the default repository star/starters:

star repo list
✨ no config found — creating one at ~/.config/star/star.config.toml
? Include the default repository star/starters? (Y/n)
✓ star/starters added, pinned @ ae3b135
star/starters  ae3b135  https://git.jingus.dev/star/starters

Non-interactive (piped, scripted) runs take the default — include it — and print a note. A script never blocks on a prompt.

Scaffold a project

star use rust-cli my-app     # by template name (searches all configured repos)

Or be explicit about where the template lives:

star use jingus/starters#rust-cli my-app     # namespace-qualified
star use https://git.jingus.dev/jingus/starters#rust-cli my-app   # ad-hoc URL, no config needed

If the target directory is not empty, star asks before writing anything — and it only ever adds files, never deletes. When the scaffolding finishes, the template’s init-message prints:

star use rust-cli my-app
✓ found rust-cli in star/starters (pinned @ ae3b135)
✓ scaffolded 14 files into my-app/

Hope you enjoy my template! Use `nix develop` to enter the dev shell!

Manage repositories

Templates live in ordinary git repositories. Add your own:

star repo add https://git.jingus.dev/jingus/starters   # cloned, pinned to its current HEAD
star repo list                                        # namespaces + pinned commits
star repo list --templates                            # ...and every template they provide

Pins move deliberately:

star repo update jingus/starters   # one repository, to remote HEAD
star repo update                   # every repository
star repo remove jingus/starters   # drop the entry and the cached clone

Author a template

Any directory in a repository that contains a star.toml is a template:

star template new my-template   # interactive: name, author, description, init-message
star template init              # same, in the current directory

That writes a manifest like:

[template]
name = "my-template"
description = "My awesome template"
init-message = """
Hope you enjoy my template!
"""

[star]
version = "0.0.1"
ignore = ["target", "*.log"]

Add your files, commit, push — then star repo add the repository (or point collaborators at star use your-namespace/your-repo#my-template).

Where to go next