cli/docs/build-variants.md

Build Variants

The Core CLI supports a modular build system that allows you to create different binary variants with different feature sets. This is useful for creating minimal builds, specialized builds, or builds tailored to specific use cases.

Overview

The variant system works through Go's module system and selective import statements in main.go. By commenting out or including specific import statements, you can control which commands are included in the final binary.

Available Variants

Full Build (Default)

The default build includes all commands and features. This is the standard build used for development and general-purpose use.

Size: ~50-100 MB (depending on platform)

Included: All commands documented in CLI Reference

Minimal Build

A minimal build includes only essential commands, suitable for resource-constrained environments or when you only need basic functionality.

Recommended commands for minimal build:

• config - Configuration management
• help - Help system
• doctor - Environment checks
• test - Basic testing

Specialized Builds

You can create specialized builds for specific use cases:

Developer Build

Focus on development workflow commands:

• dev - Development workflow
• git - Git operations
• go - Go development
• test - Testing
• qa - Quality assurance
• docs - Documentation

DevOps Build

Focus on infrastructure and deployment:

• deploy - Deployment management
• prod - Production infrastructure
• vm - Virtual machine management
• unifi - Network management
• monitor - Security monitoring

AI/ML Build

Focus on AI and machine learning operations:

• ai - AI task management
• ml - ML pipeline
• rag - RAG system
• mcp - MCP server
• collect - Data collection

How to Create a Variant

Method 1: Comment Out Imports in main.go

Edit main.go and comment out the commands you don't want:

package main

import (
	"forge.lthn.ai/core/go/pkg/cli"

	// Essential commands
	_ "forge.lthn.ai/core/cli/cmd/config"
	_ "forge.lthn.ai/core/cli/cmd/help"
	_ "forge.lthn.ai/core/cli/cmd/doctor"

	// Development commands
	_ "forge.lthn.ai/core/cli/cmd/dev"
	_ "forge.lthn.ai/core/cli/cmd/go"
	_ "forge.lthn.ai/core/cli/cmd/test"

	// Comment out to exclude:
	// _ "forge.lthn.ai/core/cli/cmd/ai"
	// _ "forge.lthn.ai/core/cli/cmd/ml"
	// _ "forge.lthn.ai/core/cli/cmd/deploy"
	// etc.
)

func main() {
	cli.Main()
}

Then build:

task cli:build

Method 2: Create Multiple main.go Files

Create separate entry points for different variants:

# Directory structure
cmd/
  core/           # Full build
    main.go
  core-minimal/   # Minimal build
    main.go
  core-dev/       # Developer build
    main.go
  core-devops/    # DevOps build
    main.go

Each main.go includes only the relevant imports for that variant.

Build specific variant:

cd cmd/core-minimal
go build -o ../../bin/core-minimal .

Method 3: Build Tags

Use Go build tags to conditionally include commands:

//go:build !minimal
// +build !minimal

package ai

// Command registration...

Build with tags:

# Full build
go build -o bin/core .

# Minimal build
go build -tags minimal -o bin/core-minimal .

External Variant Repositories

The Core CLI architecture supports external command repositories that can be optionally included. These are commented out in main.go by default:

// Variant repos (optional — comment out to exclude)
// _ "forge.lthn.ai/core/php"
// _ "forge.lthn.ai/core/ci"

Currently Available External Repos

core/php (Archived)

PHP and Laravel development commands. Note: This has been moved to its own repository and is no longer included by default.

core/ci (Archived)

CI/CD pipeline commands. Note: This has been moved to its own repository and is no longer included by default.

To include these in your build:

1. Add the module to your go.mod:

   go get forge.lthn.ai/core/php@latest
   

2. Uncomment the import in main.go:

   _ "forge.lthn.ai/core/php"
   

3. Rebuild:

   task cli:build
   

Build Optimization

Size Optimization

For smaller binaries, use the release build with stripped symbols:

task cli:build:release

This uses the following ldflags:

-s -w  # Strip debug info and symbol table

Compression

Further reduce binary size with UPX:

# Install UPX
# macOS: brew install upx
# Linux: apt-get install upx-ucl

# Compress binary
upx --best --lzma bin/core

Note: Compressed binaries may trigger antivirus false positives and won't work with code signing on macOS.

Version Information

All builds include embedded version information via ldflags:

# View version
core --version

# Build with custom version
go build -ldflags "-X forge.lthn.ai/core/go/pkg/cli.AppVersion=1.2.3" .

The Taskfile automatically sets version info from git tags:

LDFLAGS_BASE: >-
  -X {{.PKG}}.AppVersion={{.SEMVER_VERSION}}
  -X {{.PKG}}.BuildCommit={{.SEMVER_COMMIT}}
  -X {{.PKG}}.BuildDate={{.SEMVER_DATE}}
  -X {{.PKG}}.BuildPreRelease={{.SEMVER_PRERELEASE}}

Examples

Create a Minimal Developer Build

1. Edit main.go:

package main

import (
	"forge.lthn.ai/core/go/pkg/cli"

	_ "forge.lthn.ai/core/cli/cmd/config"
	_ "forge.lthn.ai/core/cli/cmd/dev"
	_ "forge.lthn.ai/core/cli/cmd/doctor"
	_ "forge.lthn.ai/core/cli/cmd/git"
	_ "forge.lthn.ai/core/cli/cmd/go"
	_ "forge.lthn.ai/core/cli/cmd/help"
	_ "forge.lthn.ai/core/cli/cmd/test"
)

func main() {
	cli.Main()
}

2. Build:

task cli:build:release

3. Result: ~20-30 MB binary with only development commands

Create an AI/ML Specialist Build

1. Edit main.go:

package main

import (
	"forge.lthn.ai/core/go/pkg/cli"

	_ "forge.lthn.ai/core/cli/cmd/ai"
	_ "forge.lthn.ai/core/cli/cmd/collect"
	_ "forge.lthn.ai/core/cli/cmd/config"
	_ "forge.lthn.ai/core/cli/cmd/daemon"
	_ "forge.lthn.ai/core/cli/cmd/help"
	_ "forge.lthn.ai/core/cli/cmd/mcp"
	_ "forge.lthn.ai/core/cli/cmd/ml"
	_ "forge.lthn.ai/core/cli/cmd/rag"
	_ "forge.lthn.ai/core/cli/cmd/session"
)

func main() {
	cli.Main()
}

2. Build:

task cli:build:release

3. Result: Binary optimized for AI/ML workflows

Testing Variants

Test your variant to ensure all needed commands are present:

# Build variant
task cli:build

# Test available commands
./bin/core help

# Verify specific command
./bin/core dev --help

Distribution

When distributing variant builds, use clear naming:

# Good naming examples
core-full-v1.2.3-linux-amd64
core-minimal-v1.2.3-darwin-arm64
core-dev-v1.2.3-windows-amd64.exe

Include a README describing what's included in each variant.

Best Practices

1. Document your variant - Keep a record of which commands are included
2. Test thoroughly - Ensure all needed functionality is present
3. Version consistently - Use the same version numbering scheme
4. Consider dependencies - Some commands depend on others (e.g., dev uses git)
5. Keep it simple - Don't create too many variants unless necessary
6. Use release builds - Always use -s -w ldflags for distribution

Troubleshooting

Command Not Found

If a command is missing after building a variant:

1. Check that the import is uncommented in main.go
2. Verify the module is in go.mod
3. Run go mod tidy
4. Rebuild with task cli:build

Build Errors

If you get import errors:

1. Ensure all required modules are in go.mod
2. Run go mod download
3. Check for version conflicts with go mod why

Large Binary Size

If your minimal build is still too large:

1. Use release build flags: task cli:build:release
2. Remove unused commands from imports
3. Consider using UPX compression (with caveats noted above)
4. Check for large embedded assets

See Also

• CLI Reference - Complete command documentation
• Configuration - Configuration system
• Getting Started - Installation and setup