Skip to content

README.md

Latest commit

 

History

History
735 lines (521 loc) · 20 KB

README.md

File metadata and controls

735 lines (521 loc) · 20 KB
Raw

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

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