Star Setup

A lightweight CLI to clone, configure, and wire single or multi-repo ecosystems.

Note: This tool is primarily designed for my own projects and workflows. While it may work for other ecosystems, it is not guaranteed to work with all project structures or build configurations.

Quick Start

# Interactive mode
star-setup

# Single-repo mode
star-setup username/repo

# Mono-repo mode
star-setup username/repo --repos user/lib1 user/lib2

Prerequisites

• Git
• At least one supported build system:
  • CMake
  • Meson
  • npm (Node.js 22+)

Installation

Download the latest binary from Releases, or use one of the methods below.

Show installation methods

Homebrew (macOS/Linux)

brew install star-setup/tap/star-setup

npm

npm install -g @star-setup/star-setup

Shell (Linux/macOS)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/star-setup/core/releases/latest/download/star-setup-installer.sh | sh

PowerShell (Windows)

powershell -ExecutionPolicy Bypass -c "irm https://github.com/star-setup/core/releases/latest/download/star-setup-installer.ps1 | iex"

pip

pip install star-setup

Windows Installer

Download the .msi from Releases.

Build from source

cargo install --git https://github.com/star-setup/core

Usage

Flags

Connection

Flag	Description
--ssh	Clone via SSH instead of HTTPS
--https	Force HTTPS (default)

Build

Flag	Description
--build-type <TYPE>	Build type: Debug (default) or Release
--build-dir <DIR>	Build output directory (default: build)
--build-system <SYSTEM>	Skip auto-detection and use cmake, meson, or npm
--no-build	Configure only, skip build step
--clean	Remove build directory before configuring
--cmake-arg <ARG>	Pass additional argument to CMake
--meson-arg <ARG>	Pass additional argument to Meson
--watch	Generate and open watch scripts (npm mono-repo mode)
--no-watch	Skip generating watch scripts (npm mono-repo mode)
--dev	Automatically start the dev server (npm)
--no-dev	Skip opening the dev server (npm)

Mono-Repo

Flag	Description
--repos <REPOS>...	List of dependency repositories
--mono-dir <DIR>	Workspace directory (default: build-mono)
--profile <NAME>	Use a saved profile

Diagnostic

Flag	Description
--verbose	Print commands as they run
--no-verbose	Suppress verbose output (overrides config)
--dry-run	Print what would happen without making any changes
--no-dry-run	Disable dry-run mode (overrides config)
--timing	Show timing for each phase
--no-timing	Suppress timing output (overrides config)

Interactive Mode

Running star-setup without arguments launches interactive mode, guiding you through all options.

Star Setup Interactive Mode
Enter repository (user/repo or URL): user/repo
Use SSH? (y/n) [N]:
Verbose? (y/n) [N]:
Clean build directory if exists? (y/n) [N]:
Select mode: (1) Single Repo (2) Mono-Repo: 1
Build type [Debug]:
Build directory [build]:
Configure only (skip build)? (y/n) [N]:

Interactive mode complete

Single Repository Mode

Build system is auto-detected from the repository root (CMakeLists.txt → CMake, meson.build → Meson, package.json → npm). Pass --dev to launch the project's dev server after setup.

Endpoint-style npm projects (no build script) skip the build step. If there's also no dev script, --dev falls back to vercel dev when the repo looks like a Vercel project (vercel.json, an api/ directory, or @vercel/node as a dependency).

# Clone and build using a single repository
star-setup username/repo

Mono-Repo Mode

Clones multiple repositories into a single workspace and auto-detects the build system.

# Clone and build a test repo and a manual repo list
star-setup username/repo --repos user/lib1 user/lib2

# Clone and build a saved profile
star-setup --profile myprofile

# Override a profile's test repo
star-setup username/repo --profile myprofile

Workspace Structures

CMake

Generates a root CMakeLists.txt wiring all repositories as subdirectories

build-mono/
├── CMakeLists.txt  # Auto-generated root project
├── repos/
│   ├── user-my-repo/ # Test repository
│   ├── user-lib1/
│   └── user-lib2/
└── build/          # Build output

BUILD_LOCAL

Mono-repo mode sets -DBUILD_LOCAL=ON when configuring CMake. This flag tells your test repository to link against local module directories instead of fetching them remotely via FetchContent:

# In your test repo's CMakeLists.txt
if(NOT BUILD_LOCAL)
  FetchContent_Declare(mylib
    GIT_REPOSITORY https://github.com/user/mylib.git
    GIT_TAG main
  )
endif()

This allows the same repository to work both standalone (fetching dependencies automatically) and inside a mono-repo workspace (linking locally for full cross-module debugging).

Meson

Generates a root meson.build and auto-generates local .wrap files bridging canonical dependency names to cloned directories.

build-mono/
├── meson.build     # Auto-generated root project
├── repos/
│   ├── user-my-repo/ # Test repository
│   ├── user-lib1/
│   ├── user-lib2/
│   ├── lib1.wrap     # Auto-generated local wrap
│   └── lib2.wrap     # Auto-generated local wrap
└── build/          # Build output

Npm

Generates a workspace root package.json that wires all cloned repositories together using npm workspaces and forces local resolution via overrides — no changes to individual repository files. Each lib's package.json is read after cloning to extract its package name for the overrides map.

build-mono/
├── package.json    # Auto-generated workspace root with workspaces + overrides
├── watch.ps1       # Auto-generated watch script (Windows)
├── watch.sh        # Auto-generated watch script (Linux/macOS)
└── repos/
    ├── user-my-repo/ # Test repository
    ├── user-lib1/
    └── user-lib2/

Watch scripts are generated by default and run each lib's watch script if present, falling back to build -- --watch. Use --watch to open them automatically in new terminals, or --no-watch to skip generation entirely.

# Generate workspace and open watchers
star-setup username/repo --repos user/lib1 user/lib2 --watch

# Generate workspace without opening watchers
star-setup username/repo --repos user/lib1 user/lib2

# Skip watch script generation
star-setup username/repo --repos user/lib1 user/lib2 --no-watch

After setup pass --dev to launch it automatically: falls back to vercel dev if the test repo has no dev script but looks like a Vercel project. Or, run it manually from its repo directory:

cd build-mono/repos/user-my-repo
# npm run dev
# vercel dev

Workspace Mode

Manage an existing mono-repo workspace.

# Pull latest changes for all repos
star-setup workspace update

# Show status of all repos
star-setup workspace status

# Show status with ahead/behind remote
star-setup workspace status --fetch

# Remove build directory
star-setup workspace clean

Workspace flags:

Flag	Description
--path <DIR>	Workspace root directory (default: current directory)
--mono-dir <DIR>	Workspace directory name (default: build-mono)
--build-dir <DIR>	Build directory name (default: build)

Config Mode

Config files are checked in this order:

• ./.star-setup.json (current directory)
• ~/.star-setup.json (home directory)

# Initialize a default config file
star-setup config init

# Add a named config
star-setup config add myconfig --ssh --build-type Release

# List configs
star-setup config list

# Remove a config
star-setup config remove myconfig

# Use a config
star-setup username/repo --config myconfig

Profile Mode

Profiles represent a saved ecosystem of libraries commonly used together.

# Add a profile with a test repo and dependencies
star-setup profile add myprofile --test-repo user/app user/lib1 user/lib2

# Add a dependency-only profile
star-setup profile add myprofile user/lib1 user/lib2

# List profiles
star-setup profile list

# Remove a profile
star-setup profile remove myprofile

# Use a profile
star-setup --profile myprofile

Development

git clone https://github.com/star-setup/core
cd core
cargo test
cargo clippy --all-targets -- -D warnings

License

MIT License — see LICENSE for details.