cli/docs/cmd/setup/index.md

core setup

Clone repositories from registry or bootstrap a new workspace.

Overview

The setup command operates in three modes:

1. Registry mode - When repos.yaml exists nearby, clones repositories into packages/
2. Bootstrap mode - When no registry exists, clones core-devops first, then presents an interactive wizard to select packages
3. Repo setup mode - When run in a git repo root, offers to create .core/build.yaml configuration

Usage

core setup [flags]

Flags

Flag	Description
--registry	Path to repos.yaml (auto-detected if not specified)
--dry-run	Show what would be cloned without cloning
--only	Only clone repos of these types (comma-separated: foundation,module,product)
--all	Skip wizard, clone all packages (non-interactive)
--name	Project directory name for bootstrap mode
--build	Run build after cloning

---

Registry Mode

When repos.yaml is found nearby (current directory or parents), setup clones all defined repositories:

# In a directory with repos.yaml
core setup

# Preview what would be cloned
core setup --dry-run

# Only clone foundation packages
core setup --only foundation

# Multiple types
core setup --only foundation,module

In registry mode with a TTY, an interactive wizard allows you to select which packages to clone. Use --all to skip the wizard and clone everything.

---

Bootstrap Mode

When no repos.yaml exists, setup enters bootstrap mode:

# In an empty directory - bootstraps workspace in place
mkdir my-project && cd my-project
core setup

# In a non-empty directory - creates subdirectory
cd ~/Code
core setup --name my-workspace

# Non-interactive: clone all packages
core setup --all --name ci-test

Bootstrap mode:

1. Detects if current directory is empty
2. If not empty, prompts for project name (or uses --name)
3. Clones core-devops (contains repos.yaml)
4. Loads the registry from core-devops
5. Shows interactive package selection wizard (unless --all)
6. Clones selected packages
7. Optionally runs build (with --build)

---

Repo Setup Mode

When run in a git repository root (without repos.yaml), setup offers two choices:

1. Setup Working Directory - Creates .core/build.yaml based on detected project type
2. Create Package - Creates a subdirectory and clones packages there

cd ~/Code/my-go-project
core setup

# Output:
# >> This directory is a git repository
# > Setup Working Directory
#   Create Package (clone repos into subdirectory)

Choosing "Setup Working Directory" detects the project type and generates configuration:

Detected File	Project Type
wails.json	Wails
go.mod	Go
composer.json	PHP
package.json	Node.js

Creates three config files in .core/:

File	Purpose
build.yaml	Build targets, flags, output settings
release.yaml	Changelog format, GitHub release config
test.yaml	Test commands, environment variables

Also auto-detects GitHub repo from git remote for release config.

See Configuration Files for generated config examples.

---

Interactive Wizard

When running in a terminal (TTY), the setup command presents an interactive multi-select wizard:

• Packages are grouped by type (foundation, module, product, template)
• Use arrow keys to navigate
• Press space to select/deselect packages
• Type to filter the list
• Press enter to confirm selection

The wizard is skipped when:

• --all flag is specified
• Not running in a TTY (e.g., CI pipelines)
• --dry-run is specified

---

Examples

Clone from Registry

# Clone all repos (interactive wizard)
core setup

# Clone all repos (non-interactive)
core setup --all

# Preview without cloning
core setup --dry-run

# Only foundation packages
core setup --only foundation

Bootstrap New Workspace

# Interactive bootstrap in empty directory
mkdir workspace && cd workspace
core setup

# Non-interactive with all packages
core setup --all --name my-project

# Bootstrap and run build
core setup --all --name my-project --build

---

Registry Format

The registry file (repos.yaml) defines repositories. See Configuration Files for format.

---

Finding Registry

Core looks for repos.yaml in:

1. Current directory
2. Parent directories (walking up to root)
3. ~/Code/host-uk/repos.yaml
4. ~/.config/core/repos.yaml

---

After Setup

# Check workspace health
core dev health

# Full workflow (status + commit + push)
core dev work

# Build the project
core build

# Run tests
core go test    # Go projects
core php test   # PHP projects

---

See Also

• dev work - Multi-repo operations
• build - Build projects
• doctor - Check environment