cli/docs/getting-started.md

Getting Started

This guide walks you through installing Core and running your first build.

Prerequisites

Before installing Core, ensure you have:

Tool	Minimum Version	Check Command
Go	1.23+	go version
Git	2.30+	git --version

Optional (for specific features):

Tool	Required For	Install
gh	GitHub integration (core dev issues, core dev reviews)	cli.github.com
Docker	Container builds	docker.com
task	Task automation	go install github.com/go-task/task/v3/cmd/task@latest

Installation

Option 1: Go Install (Recommended)

# Install latest release
go install forge.lthn.ai/core/cli/cmd/core@latest

# Verify installation
core doctor

If core: command not found, add Go's bin directory to your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Option 2: Download Binary

Download pre-built binaries from GitHub Releases:

# macOS (Apple Silicon)
curl -Lo core https://forge.lthn.ai/core/cli/releases/latest/download/core-darwin-arm64
chmod +x core
sudo mv core /usr/local/bin/

# macOS (Intel)
curl -Lo core https://forge.lthn.ai/core/cli/releases/latest/download/core-darwin-amd64
chmod +x core
sudo mv core /usr/local/bin/

# Linux (x86_64)
curl -Lo core https://forge.lthn.ai/core/cli/releases/latest/download/core-linux-amd64
chmod +x core
sudo mv core /usr/local/bin/

Option 3: Build from Source

# Clone repository
git clone https://forge.lthn.ai/core/cli.git
cd core

# Build with Task (recommended)
task cli:build
# Binary at ./bin/core

# Or build with Go directly
CGO_ENABLED=0 go build -o core ./cmd/core/
sudo mv core /usr/local/bin/

Your First Build

1. Navigate to a Go Project

cd ~/Code/my-go-project

2. Initialise Configuration

core setup

This detects your project type and creates configuration files in .core/:

• build.yaml - Build settings
• release.yaml - Release configuration
• test.yaml - Test commands

3. Build

core build

Output appears in dist/:

dist/
├── my-project-darwin-arm64.tar.gz
├── my-project-linux-amd64.tar.gz
└── CHECKSUMS.txt

4. Cross-Compile (Optional)

core build --targets linux/amd64,linux/arm64,darwin/arm64,windows/amd64

Your First Release

Releases are safe by default - Core runs in dry-run mode unless you explicitly confirm.

1. Preview

core ci

This shows what would be published without actually publishing.

2. Publish

core ci --we-are-go-for-launch

This creates a GitHub release with your built artifacts.

Multi-Repo Workflow

If you work with multiple repositories (like the host-uk ecosystem):

1. Clone All Repositories

mkdir host-uk && cd host-uk
core setup

Select packages in the interactive wizard.

2. Check Status

core dev health
# Output: "18 repos │ clean │ synced"

3. Work Across Repos

core dev work --status    # See status table
core dev work             # Commit and push all dirty repos

Next Steps

Task	Command	Documentation
Run tests	core go test	go/test
Format code	core go fmt --fix	go/fmt
Lint code	core go lint	go/lint
PHP development	core php dev	php
View all commands	core --help	cmd

Getting Help

# Check environment
core doctor

# Command help
core <command> --help

# Full documentation
https://forge.lthn.ai/core/cli/tree/main/docs

See Also

• Configuration - All config options
• Workflows - Common task sequences
• Troubleshooting - When things go wrong