Sun Agent Kit CLI

Command-line tool for bootstrapping and managing Sun Agent Kit projects.

Overview

sk manages Sun Agent Kit installations — install, update, migrate, and configure kits from GitHub releases. Built with Bun + TypeScript for development; published CLI runs on plain Node.js.

Key features:

• Install/update kits from GitHub releases or local archives
• Smart merge with user customization preservation
• Multi-tier GitHub auth (gh CLI, env vars, keychain, prompt)
• Idempotent migration with 3-phase reconciliation
• Cross-platform: macOS, Linux, Windows

Prerequisites

1. GitHub access to sun-asterisk-internal/agent-kit
2. GitHub CLI installed and authenticated: gh auth login
3. Node.js 18+ (runtime) or Bun (development)

Installation

npm install -g sun-agent-kit-cli

Verify: sk --version

Usage

Quick Start

sk --help                      # All commands
sk new                         # Create new project (interactive)
sk new --kit engineer          # Create with specific kit
sk init                        # Initialize/update in current project
sk init -g -y                  # Global install, non-interactive

Create New Project

sk new                                  # Interactive
sk new --dir my-project --kit engineer  # With options
sk new --archive ~/kit.zip              # Offline install
sk new --install-skills                 # Auto-install skill deps
sk new --prefix                         # /sk: namespace for commands

Initialize or Update

Run from project root:

sk init                        # Interactive
sk init -y                     # Non-interactive, latest version
sk init -g --kit engineer -y   # Global install
sk init --fresh                # Clean reinstall (destructive)
sk init --archive ~/kit.zip    # Offline install
sk init --local                # From local monorepo (development)

Update CLI

sk update                      # Update to latest
sk update --check              # Check only
sk update --version 1.1.3     # Specific version

Diagnostics

sk doctor                      # Full health check
sk doctor --fix                # Auto-fix issues
sk doctor --report             # Shareable diagnostic report

Skills & Agents

sk skills --help               # Skill management
sk agents --help               # Agent management
sk commands --help             # Command discovery

Other Commands

sk versions                    # List available versions
sk migrate                     # Run migration pipeline
sk uninstall                   # Remove Sun Agent Kit
sk config get defaults.kit     # Read config
sk config set defaults.kit engineer  # Write config

Debugging

sk new --verbose                       # Verbose logging
sk new --verbose --log-file debug.log  # Save to file
SUN_AGENT_KIT_VERBOSE=1 sk new        # Via env var

Authentication

1. GitHub CLI (gh auth token)
   ↓ fallback
2. Environment Variables (GITHUB_TOKEN)
   ↓ fallback
3. Config File (~/.sun-agent-kit/config.json)
   ↓ fallback
4. OS Keychain
   ↓ fallback
5. User Prompt (with save option)

Recommended: gh auth login with web browser OAuth.

Configuration

Stored in ~/.sun-agent-kit/config.json:

{
  "github": { "token": "stored_in_keychain" },
  "defaults": { "kit": "engineer", "dir": "." }
}

Protected Files

Never overwritten during updates: .env*, *.key, *.pem, node_modules/**, .git/**, dist/**

Development

bun install                    # Install deps
bun run dev new --kit engineer # Run locally
bun test                       # Run tests (3600+ tests)
bun run lint:fix               # Auto-fix lint
bun run typecheck              # Type check
bun run build                  # Build for npm
bun run validate               # Full quality gate

See AGENTS.md for project structure and coding patterns.

License

Internal use — Sun Asterisk.