A.R.C. CLI

Agent Runtime Core - Reliable Components for Resilient Architecture

A powerful CLI tool for managing and orchestrating infrastructure with AI-powered assistance.

Installation

🍺 Homebrew (Recommended for macOS / Linux)

brew tap arc-framework/tap
brew install arc

To upgrade later:

brew upgrade arc

📦 One-Line Installer (macOS / Linux / Windows)

macOS / Linux:

curl -sSL https://raw.githubusercontent.com/arc-framework/arc-cli/main/install.sh | bash

If Homebrew is installed, the script will use it automatically. Otherwise it downloads the binary directly.

Windows (PowerShell):

irm https://raw.githubusercontent.com/arc-framework/arc-cli/main/install.ps1 | iex

📦 Manual Download

Download the binary directly from Releases:

Pick the right file for your system:

• Mac (Apple Silicon M1/M2/M3): arc-cli_darwin_arm64.tar.gz
• Mac (Intel): arc-cli_darwin_amd64.tar.gz
• Linux (ARM64): arc-cli_linux_arm64.tar.gz
• Linux (x64): arc-cli_linux_amd64.tar.gz
• Windows: arc-cli_windows_amd64.zip

Then extract and install:

macOS/Linux:

tar -xzf arc-cli_*.tar.gz
sudo mv arc /usr/local/bin/
arc version

Windows:

• Extract the ZIP file
• Move arc.exe to a folder in your PATH

🔧 From Source (Developers)

For developers who want to build from source:

# Clone the repository
git clone https://github.com/arc-framework/arc-cli.git
cd cli

# Build the binary
go build -o arc cmd/arc/main.go

# Move to PATH (optional)
sudo mv arc /usr/local/bin/

See the Development section for more build options.

Quick Start

Verify Installation

# Check version
arc --version

# Get help
arc --help

For Developers

Run without building:

go run cmd/arc/main.go

Build from source:

make build
# or
go build -o arc cmd/arc/main.go

Create a new feature branch:

# Use the helper script (automatically determines next PR number)
./scripts/new-branch.sh

# Example: Creates branch like 007-state-management for PR #7

📝 Note: We use PR-number-based branching (e.g., 007-feature-name). See BRANCHING_CONVENTION.md for details.

Features

• 🌀 Beautiful Interactive UI with smooth animations and styled output
• 🖥️ New UI Engine (017) — unified view-based architecture with TUI, JSON, and static output modes; profile-aware theming across all commands; ARC_USE_LEGACY_UI=1 for rollback
• 🎨 5+ Animated Theme Schemes with live previews
  • Cyan→Purple (default), Rainbow, Fire, Ocean, Matrix
  • Character-by-character rainbow option for maximum color!
• 📊 Interactive Info Command - System information with animated spinners
• 🎭 Smart Terminal Detection - Adapts to terminal capabilities automatically
• 📝 Structured Logging - Leveled logs with colors and file rotation
• 🚀 Progress Indicators - Animated progress bars for long-running operations
• 🔧 Shell Completion - Interactive setup for bash, zsh, fish, powershell
• 🎯 Fast & Zero-Dependency - Single binary, no runtime dependencies
• 🌈 Graceful Degradation - Works in any terminal (respects NO_COLOR)
• 🎪 Spring-Based Animations - Smooth 60fps color transitions

Usage

Basic Commands

# Show banner and help
arc

# Show help
arc --help

# Show version information
arc version

# Show system information (NEW!)
arc info

# Initialize a new A.R.C. environment (NEW!)
arc init

# Disable colored output
arc --no-color

# Enable verbose logging
arc --verbose

# Set log level
arc --log-level=debug

# Theme Management
arc theme list                # List all available themes
arc theme set <name>          # Set a theme (persists across sessions)
arc theme show                # Preview current theme
arc theme preview <name>      # Animated theme preview (NEW!)

# Shell Completion (NEW!)
arc completion bash           # Generate bash completion
arc completion zsh            # Generate zsh completion
arc completion fish           # Generate fish completion
arc completion powershell     # Generate PowerShell completion
arc completion --interactive  # Interactive setup wizard

Workspace Management

A.R.C. workspaces let you declare your desired infrastructure state in arc.yaml and generate complete Docker Compose configurations automatically.

# Initialize a new workspace
arc workspace init

# Generate configs and launch the platform
arc workspace run

# View workspace status
arc workspace info

# View operation history
arc workspace history

Quick Start:

# 1. Create a new workspace
arc workspace init ./my-project
cd my-project

# 2. Edit arc.yaml to enable features
# features:
#   voice: true
#   security: true
#   observability: true

# 3. Generate and run
arc workspace run --detached

Workspace Commands:

Command	Description
arc workspace init [path]	Initialize a new workspace
arc workspace run	Generate configs and launch platform
arc workspace run --generate-only	Generate configs without launching
arc workspace info	Show workspace state and configuration
arc workspace history	Show operation history

See Workspace Quickstart for detailed documentation.

Profile System

Customize tier naming throughout A.R.C. CLI with themed profiles. Choose from 10 built-in profiles or create your own.

# List all available profiles
arc config list-profiles

# Set a profile (changes tier names globally)
arc config set-profile jedi

# Show current profile
arc config get-profile

Built-in Profiles:

Profile	Tier 1	Tier 2	Tier 3	Theme
enterprise	Starter	Pro	Ultra	Professional
saiyan	Super Saiyan	Super Saiyan Blue	Ultra Instinct	Dragon Ball Z
shinobi	Genin	Jonin	Hokage	Naruto
pirate	Rookie	Supernova	Yonko	One Piece
pokemon	Basic	Stage 1	Stage 2	Pokemon
triforce	Courage	Wisdom	Power	Zelda
crystal	Warrior	Knight	Paladin	Final Fantasy
jedi	Padawan	Knight	Master	Star Wars
bending	Bender	Avatar	Cosmic	Avatar
horcrux	Student	Auror	Headmaster	Harry Potter

Example:

arc config set-profile jedi       # Set Star Wars theme
arc workspace init                # Tiers now show as Padawan/Knight/Master
arc config set-profile enterprise # Reset to default

Custom Profiles: Create ~/.config/arc/profiles/custom.yaml:

id: custom
name: My Custom Profile
description: Personalized tier names
tier_names:
  - Bronze
  - Silver
  - Gold
theme_id: fire
logo: |
  A.R.C.
  Custom Edition

See Profile System Guide for detailed documentation.

Environment Initialization (Legacy)

The arc init command provides an interactive wizard to set up your A.R.C. development environment:

arc init

Features:

• Interactive TUI with keyboard navigation
• Multiple tier options for different use cases
• Quick environment setup

Note: For workspace-based development, use arc workspace init instead.

Available Themes:

• cyan-purple (default) - Modern & Professional gradient
• rainbow - Full spectrum rainbow
• fire - Yellow to red gradient
• ocean - Cool blue tones
• matrix - Green hacker style
• character-rainbow - Ultimate colors! (every character is different)

Example:

arc theme set rainbow       # Switch to rainbow theme
arc                         # See the rainbow banner!
arc theme preview ocean     # Preview ocean theme with animation
arc theme set cyan-purple   # Switch back to default

# Setup shell completion
arc completion --interactive  # Guided setup

Environment Variables

The CLI respects several environment variables for customization:

• NO_COLOR - Disable all colors (e.g., NO_COLOR=1 arc)
• CLICOLOR_FORCE - Force color output even in non-TTY environments
• ARC_NO_ANIMATION - Disable animations (e.g., ARC_NO_ANIMATION=1 arc)
• TERM - Terminal type detection (auto-detected)
• COLORTERM - True color support detection (auto-detected)
• SHELL - Shell detection for completion (auto-detected)

Examples:

# Disable colors for scripting
NO_COLOR=1 arc info

# Disable animations but keep colors
ARC_NO_ANIMATION=1 arc theme preview ocean

# Force colors in CI/CD
CLICOLOR_FORCE=1 arc --verbose

Example Output

======================================
====  =========       =========     ==
===    ========  ====  =======  ===  =
==  ==  =======  ====  ======  =======
=  ====  ======  ===   ======  =======
=  ====  ======      ========  =======
=        ======  ====  ======  =======
=  ====  ======  ====  ======  =======
=  ====  ==  ==  ====  ==  ===  ===  =
=  ====  ==  ==  ====  ==  ====     ==
======================================

A.R.C. CLI 0.0.1-dev
Reliable Components for Resilient Architecture

(With beautiful cyan→purple gradient colors in your terminal!)

Environment Variables

The A.R.C. CLI respects several environment variables for customization:

Color Control

• NO_COLOR - Disable all colored output (any value disables colors)
• CLICOLOR_FORCE=1 - Force colored output even in non-TTY environments
• COLORTERM=truecolor or COLORTERM=24bit - Enable 24-bit true color support
• TERM - Terminal type (e.g., xterm-256color, screen-256color)

Animation Control

• ARC_NO_ANIMATION=1 - Disable all animations (banner, theme previews, spinners)
• ARC_ANIMATION_FPS=30 - Set target FPS for animations (default: 60)

Logging

• ARC_LOG_LEVEL - Set log level: debug, info, warn, error, fatal (default: info)
• ARC_LOG_FILE - Custom log file path (default: .arc/logs/arc.log)

State Storage

• ARC_STATE_DIR - Custom state directory (default: .arc)

Examples:

# Disable all colors and animations
NO_COLOR=1 ARC_NO_ANIMATION=1 arc info

# Enable debug logging
ARC_LOG_LEVEL=debug arc --verbose

# Use custom state directory
ARC_STATE_DIR=/tmp/arc-state arc state show

Development

Using Make (Easiest)

# Show all available commands
make help

# Development
make build              # Build the binary
make run                # Run without building
make test               # Run tests
make fmt                # Format code
make clean              # Clean built files

# Release Management (GoReleaser)
make release-check      # Validate release config
make release-test       # Test build (current platform)
make release-build      # Build for all platforms
make release-snapshot   # Full release dry-run

Release Strategy

We use a dual-release strategy:

• Stable releases: Official production builds (v1.0.0, v1.2.3)
• Feature releases: Temporary test builds for feature branches (auto-cleanup)

📖 Read the full Release Strategy Guide for details on:

• Creating stable releases
• Testing feature branches
• Managing draft releases
• Troubleshooting upload issues

Running from Source

go run cmd/arc/main.go

Building Manually

go build -o arc cmd/arc/main.go
./arc

Testing

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run integration tests
make test-integration

# Generate HTML coverage report
make test-coverage-html

📖 Read the full Testing Guide for details on:

• Writing tests with testify
• Using test utilities and mocks
• Test organization and patterns
• Coverage guidelines and best practices

PR Management

# Generate PR description (after passing pre-commit checks)
make gen-pr

# Or generate PR description only
make pr-desc-full

📖 Read the PR Generator Guide for details on:

• Automated PR description generation
• Coverage analysis and statistics
• Customizing PR templates
• Integration with pre-commit hooks

Project Structure

arc/
├── cmd/arc/                    # CLI entry point
├── internal/                   # Private application code
│   ├── branding/              # Branding constants (tagline, name)
│   ├── state/                 # State management (persisted settings)
│   └── version/               # Version information
├── pkg/                        # Public reusable packages
│   ├── cli/                   # CLI commands and handlers
│   └── ui/                    # UI components and styling
│       ├── components/        # Reusable UI components
│       ├── layout/            # Layout helpers
│       ├── markdown/          # Markdown rendering
│       ├── styles/            # Colors, emoji, output helpers
│       └── themes/            # Theme system
├── specs/                      # Feature specifications
│   ├── 001-initial-setup/     # ✅ Complete (PR #4)
│   └── 002-state-management/  # 📝 Ready (PR #7 expected)
├── docs/                       # Documentation
│   ├── README.md              # Documentation index
│   ├── BRANCHING_CONVENTION.md # Branch naming guide
│   ├── DEVELOPMENT.md         # Development practices
│   └── ...                    # More guides
├── scripts/                    # Helper scripts
│   ├── new-branch.sh          # Create new feature branch
│   └── setup-dev.sh           # Development setup
└── go.mod                      # Go module dependencies

Feature Development

Features are developed using a spec-driven approach:

1. Spec Directory: Each feature has a directory in specs/ (e.g., 002-state-management/)
2. Branch Naming: Branches use PR numbers (e.g., 007-state-management)
3. Documentation: Each spec includes:

• spec.md - Feature specification
• plan.md - Implementation plan
• tasks.md - Detailed task breakdown

Current Features:

• ✅ 001-initial-setup (PR #4) - CLI foundation, banner, styling
• 📝 002-state-management (PR #7) - State persistence, history tracking

See specs/README.md and docs/contributing/branching.md for details.

Documentation

📚 Full Documentation Index

Quick Links

• Getting Started - First steps
• Development Guide - Contributing and testing
• Branching Convention - PR-based workflow
• Theme Guide - Customizing themes
• Profile System - Profile and tier customization
• Release System - Managing releases
• Workspace Guide - Workspace management

Customization

Changing the Tagline

The tagline "Reliable Components for Resilient Architecture" is centralized in one file for easy customization:

File: internal/branding/branding.go

Simply edit the Tagline constant:

const (
    Tagline = "Your Custom Tagline Here"
)

After changing, rebuild the CLI:

go build -o arc cmd/arc/main.go

The new tagline will automatically appear in:

• Banner display
• Help text
• Version output

Note: Don't forget to update this README manually to match your new tagline!

Changing Banner Colors 🎨

Easy Way (Recommended): Use the theme command!

# List all available themes
arc theme list

# Set a theme (persists across sessions!)
arc theme set rainbow

# Preview the current theme
arc theme show

The theme is automatically saved to ~/.arc/state.json and persists across all sessions.

Available Themes:

• 🌀 cyan-purple (default) - Professional gradient
• 🌈 rainbow - Full spectrum
• 🔥 fire - Yellow to red
• 🌊 ocean - Cyan to deep blue
• 💻 matrix - Green gradient
• ✨ character-rainbow - Ultimate colors! (every character different)

Advanced Way: Modify the code

If you want to create custom themes:

1. Open pkg/cli/banner.go
2. Add your theme to AvailableThemes() function
3. Rebuild: make build
4. Use: arc theme set your-theme-name

📖 Full Guide: See docs/ASCII_COLOR_GUIDE.md for detailed instructions!

License

MIT License

FAQ

Why do commands exit immediately?

This is normal behavior for CLI tools! The A.R.C. CLI is designed like git, docker, or ls - it:

1. Runs a command
2. Shows output
3. Exits

This is NOT a server or daemon - it's a command-line tool that performs tasks and completes.

Examples:

./arc version      # Shows version and exits ✅
./arc --help       # Shows help and exits ✅
make test          # Runs tests and exits ✅

Releases

A.R.C. CLI supports two types of automated releases:

🚀 Main Releases (Stable)

Production-ready releases for end users:

# Create a stable release
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

# GitHub Actions automatically builds and publishes

🚧 Feature Releases (Pre-release/Beta)

Test and preview builds from feature branches or beta tags:

# Option 1: Push a numbered feature branch (Specify convention)
git checkout -b 042-awesome-thing
git push origin 042-awesome-thing

# Option 2: Push a legacy feature branch
git checkout -b feature/awesome-thing
git push origin feature/awesome-thing

# Option 3: Create a pre-release tag
git tag -a v1.0.0-beta1 -m "Beta 1"
git push origin v1.0.0-beta1

# All create pre-releases for testing

Branch Naming Conventions

A.R.C. CLI supports two conventions:

Convention	Format	Example	Use Case
Specify (⭐ Recommended)	###-name	042-add-auth	Spec-driven development
Legacy	feature/* or feat/*	feature/quick-fix	Quick features

Quick Guide

What	How	Creates
Stable Release	Push v* tag	Official release
Feature Release (Specify)	Push ###-* branch	Pre-release
Feature Release (Legacy)	Push feature/** branch	Pre-release
Beta Release	Push v*-beta* tag	Pre-release
Local Test	make release-test	Local build only

📚 See RELEASE_SYSTEM.md for the complete release guide Includes: Branch conventions, workflows, troubleshooting, and step-by-step guides

How do I keep it running?

You don't! CLI tools are meant to be called repeatedly for different tasks:

# Each command runs independently
./arc version
./arc deploy myapp
./arc status

If you need a long-running process, that would be a different command (like arc serve or arc watch) which we can add in future phases.

How do I actually use the CLI?

Quick start:

# Option 1: Use the demo script
./demo.sh

# Option 2: Build and run
make build
./arc

# Option 3: Run directly
go run cmd/arc/main.go