star use

planned

planned landing in phase 4 of the roadmap — the full CLI grammar parses today.

Synopsis

star use <template> [target] [--force]

target defaults to the current directory — scaffold into . when you mean it.

<template> is a reference: a bare name (rust-cli), a namespace-qualified form (jingus/starters#rust-cli), or a URL-qualified form (https://git.jingus.dev/jingus/starters#rust-cli).

What it does

Resolve the reference to exactly one template.
- Unqualified names are searched across all configured repositories.
  - 0 matches → error, with a did-you-mean over every known template name.
  - 1 match → proceed.
  - Several matches → interactive: pick from namespace#name — description; non-interactive: the error is the disambiguation:
    star — disambiguation
```
star use rust-cli my-app
error: template `rust-cli` is provided by 2 repositories:
star use jingus/starters#rust-cli my-app
star use star/starters#rust-cli my-app
```
- Qualified / URL references target one repository; a miss gets a did-you-mean over that repository’s templates.
Fetch — configured repositories are read at their pin (fetched into the cache if stale); URL references clone at remote HEAD and are never pinned.
Guard — if the target directory is non-empty (any entry counts, including dotfiles and .git), confirm interactively, or require --force when not attached to a TTY.
Materialize the template tree into the target under the shared ignore pipeline — .gitignore honored, [star] ignore layered on top, .git skipped, and star.toml never copied.
Report — print what was created, then the template’s init-message, if it has one.

Examples

star use rust-cli my-app                       # by name, from any configured repository
star use jingus/starters#rust-cli my-app       # qualified, unambiguous
star use rust-cli                              # scaffold into the current directory
star use rust-cli my-app --force               # skip the non-empty confirmation
star use https://git.jingus.dev/jingus/starters#rust-cli my-app   # ad-hoc, no config entry

Flags

Flag	Effect
`--force`	Proceed into a non-empty target without the interactive confirmation.
`target` (positional)	Destination directory; defaults to `.`. Created if missing.

Details worth knowing

Non-empty means any entry — .git counts, so scaffolding into an existing repository is explicitly a confirm-worthy event.
URL references without a template name are an error — with the fix appended (…#rust-cli), because a bare URL names a repository, not a template.
Symlinks inside templates are copied as symlinks; anything resolving outside the template root is skipped with a warning rather than followed. See security.