Funv CLI

Command-line tool for bootstrapping and updating Funv projects.

Version: 1.16.0

Overview

Funv CLI (funv) is a command-line tool for bootstrapping and updating projects from private GitHub releases. Built with Bun and TypeScript, provides fast, secure project setup and maintenance.

Key Features:

• Multi-tier GitHub authentication (gh CLI → env vars → keychain → prompt)
• Streaming downloads with progress tracking and platform optimizations
• Offline installation from local archives or directories
• Smart file merging with conflict detection
• Automatic skills directory migration with parallel processing
• Secure credential storage using OS keychain
• Beautiful CLI interface with interactive prompts
• Optional package installation (OpenCode, Gemini)
• System dependency auto-installation
• Platform-specific optimizations (macOS native unzip, adaptive concurrency)
• Intelligent update notifications with 7-day cache

Documentation

Comprehensive documentation in /docs:

• Codebase Summary - Overview, structure, key components
• Project Overview & PDR - Requirements, features, roadmap
• System Architecture - Architecture diagrams, data flow
• Code Standards - Coding conventions, best practices
• Project Roadmap - Release timeline, feature status
• Deployment Guide - Release procedures

Prerequisites

Before using Funv CLI, you need to:

1. Purchase a Funv Starter Kit from funv.io
2. Get Repository Access: After purchase, you'll receive access to the private GitHub repository containing your kit
3. Create a GitHub Personal Access Token (PAT) with repo scope to download releases

Without a purchased kit and repository access, the CLI will not be able to download any project templates.

Installation

The Funv CLI is published on npm at npmjs.com/package/funv-cli.

Using npm (Recommended)

npm install -g funv-cli

Using Bun

bun add -g funv-cli

Using Yarn

yarn global add funv-cli

Using pnpm

pnpm add -g funv-cli

After installation, verify it's working:

ck --version

Usage

Create New Project

# Interactive mode
funv new

# With options
funv new --dir my-project --kit engineer

# Show beta versions
funv new --beta

# With exclude patterns
funv new --exclude "*.log" --exclude "temp/**"

# Optional packages (OpenCode, Gemini)
funv new --opencode --gemini

# Install skills dependencies (Python, Node packages, system tools)
funv new --install-skills

# Command prefix (/ck: namespace to avoid conflicts)
funv new --prefix

# Offline installation (from local archive or directory)
funv new --archive ~/downloads/engineer-v1.16.0.zip
funv new --kit-path ~/extracted-kit/

Flags:

• --install-skills: Auto-install Python packages, system tools (FFmpeg, ImageMagick), Node.js packages
• --prefix: Move commands to /ck: namespace (/plan → /ck:plan)
• --beta: Show pre-release versions in selection
• --opencode/--gemini: Install optional packages
• --archive <path>: Use local archive (zip/tar.gz) instead of downloading
• --kit-path <path>: Use local kit directory instead of downloading

Initialize or Update Project

Note: Run from project root.

# Interactive mode
funv init

# Non-interactive mode with sensible defaults
funv init --yes
funv init -y

# Combine with other flags
funv init -g --kit engineer -y

# With options
funv init --kit engineer --beta

# Global mode (platform-specific paths)
funv init --global

# Fresh installation (⚠️ DESTRUCTIVE - removes ALL customizations)
funv init --fresh

# With exclude patterns and prefix
funv init --exclude "*.local" --prefix

# Offline installation (from local archive or directory)
funv init --archive ~/downloads/engineer-v1.16.0.zip
funv init --kit-path ~/extracted-kit/

Flags:

• --yes/-y: Non-interactive mode with sensible defaults (skip all prompts)
• --global/-g: Use platform-specific config (macOS/Linux: ~/.claude, Windows: %USERPROFILE%.claude)
• --fresh: Clean reinstall, removes .claude directory (requires "yes" confirmation)
• --beta: Show pre-release versions
• --prefix: Apply /ck: namespace to commands
• --archive <path>: Use local archive (zip/tar.gz) instead of downloading
• --kit-path <path>: Use local kit directory instead of downloading

Default Behavior with -y Flag:

| Prompt | Default | |--------|---------| | Select ClaudeKit | engineer (first option) | | Target directory | Current directory (.) | | Version selection | Latest stable release | | Google Gemini setup | Skip | | Other optional features | Skip |

Update CLI

Keep the Funv CLI up to date:

# Check for CLI updates
funv update --check

# Update to latest version
funv update

# Update to specific version
funv update --version 1.17.0

# Update to beta / skip confirmation
funv update --beta
funv update --yes

The CLI notifies you when updates are available via ck --version.

Skills Migration:

• Auto-detects structure changes (flat → categorized)
• Preserves customizations (SHA-256 hashing)
• Creates backup before migration
• Rollback on failure

List Available Versions

# Show all available versions for all kits
funv versions

# Filter by specific kit
funv versions --kit engineer
funv versions --kit marketing

# Show more versions (default: 30)
funv versions --limit 50

# Include prereleases and drafts
funv versions --all

Diagnostics & Doctor

# Full health check (default)
funv doctor

# Verbose mode with execution timing and command details
funv doctor --verbose

# Generate shareable diagnostic report (prompts for gist upload)
funv doctor --report

# Auto-fix all fixable issues
funv doctor --fix

# CI mode: no prompts, exit 1 on failures
funv doctor --check-only

# Machine-readable JSON output
funv doctor --json

# Combine flags
funv doctor --verbose --check-only --json
funv doctor --verbose --fix

Health Checks:

• System: Node.js, npm, Python, pip, Claude CLI, git, gh CLI
• ClaudeKit: Global/project installation, versions, skills
• Auth: GitHub CLI authentication, repository access
• Project: package.json, node_modules, lock files
• Modules: Dynamic skill dependency resolution

Auto-Fix Capabilities: | Issue | Fix Action | |-------|------------| | Missing dependencies | Install via package manager | | Missing gh auth | Run gh auth login | | Corrupted node_modules | Reinstall dependencies | | Missing global install | Run funv init --global | | Missing skill deps | Install in skill directory |

Exit Codes:

• 0: All checks pass or issues fixed
• 1: Failures detected (only with --check-only)

Note: ck diagnose is deprecated. Use funv doctor instead.

Uninstall

Remove ClaudeKit installations from your system:

funv uninstall              # Interactive mode - prompts for scope and confirmation
funv uninstall --local      # Uninstall only local installation (current project)
funv uninstall --global     # Uninstall only global installation (~/.claude/)
funv uninstall -l -y        # Local only, skip confirmation
funv uninstall -g -y        # Global only, skip confirmation
funv uninstall --yes        # Non-interactive - skip confirmation (for scripts)

Scope Selection:

• When both local and global installations exist, you'll be prompted to choose:
  • Local only: Remove from current project (.claude/)
  • Global only: Remove from user directory (~/.claude/)
  • Both: Remove all ClaudeKit installations
• Use --local or --global flags to skip the prompt

What it does:

• Detects local .claude directory in current project
• Detects global ~/.claude ClaudeKit installation
• Shows paths before deletion
• Requires confirmation (unless --yes flag)
• Removes ClaudeKit subdirectories (commands/, agents/, skills/, workflows/, hooks/, metadata.json)
• Preserves user configs like settings.json, settings.local.json, and CLAUDE.md

Note: Only removes valid ClaudeKit installations (with metadata.json). Regular .claude directories from Claude Desktop are not affected.

Other Commands

# Show CLI version (shows local + global kit versions)
ck --version

# Show help
ck --help
ck -h

# Command-specific help
funv new --help
funv init --help
funv versions --help

Debugging

funv new --verbose              # Enable verbose logging
funv new --verbose --log-file debug.log  # Save to file
CLAUDEKIT_VERBOSE=1 funv new   # Via environment variable

Cache Configuration

Release data is cached locally to improve performance. You can configure the cache TTL:

# Set custom cache TTL (in seconds, default: 3600 = 1 hour)
CK_CACHE_TTL=7200 funv versions    # Cache for 2 hours
CK_CACHE_TTL=0 funv versions       # Disable caching (always fetch fresh)

# Permanent configuration (add to ~/.bashrc or ~/.zshrc)
export CK_CACHE_TTL=1800         # 30 minutes

Cache Location: ~/.claudekit/cache/releases/

Update Notifications

The ck --version command checks for newer versions of your installed ClaudeKit and displays a notification if an update is available. The check is cached for 7 days to minimize API calls.

Disable Update Notifications:

# Set environment variable to disable
NO_UPDATE_NOTIFIER=1 ck --version

# Windows (permanent)
[System.Environment]::SetEnvironmentVariable("NO_UPDATE_NOTIFIER", "1", [System.EnvironmentVariableTarget]::User)

# macOS/Linux (add to ~/.bashrc or ~/.zshrc)
export NO_UPDATE_NOTIFIER=1

Cache Location: ~/.claudekit/cache/version-check.json (Windows: %USERPROFILE%\.claudekit\cache\)

Authentication

The CLI requires GitHub authentication to download releases from private repositories.

Authentication Flow

┌─────────────────────────────────────────────────┐
│          Multi-Tier Authentication               │
│                                                  │
│  1. GitHub CLI (gh auth token)                  │
│       ↓ (if not available)                       │
│  2. Environment Variables (GITHUB_TOKEN)        │
│       ↓ (if not set)                             │
│  3. Config File (~/.claudekit/config.json)      │
│       ↓ (if not found)                           │
│  4. OS Keychain (secure storage)                │
│       ↓ (if not stored)                          │
│  5. User Prompt (with save option)              │
└─────────────────────────────────────────────────┘

Quick Setup

Step 1: Install GitHub CLI

# Windows
winget install GitHub.cli

# macOS
brew install gh

# Linux
sudo apt install gh

Step 2: Authenticate with GitHub CLI

gh auth login

When prompted, follow these steps:

1. Select GitHub.com
2. Select HTTPS (or SSH if preferred)
3. Authenticate Git? → Yes
4. Select Login with a web browser (⚠️ recommended)
5. Copy the one-time code shown
6. Press Enter to open browser and paste the code
7. Authorize GitHub CLI

⚠️ Important: Select "Login with a web browser" - do NOT use "Paste an authentication token" as PAT authentication is no longer supported for accessing private repositories.

Troubleshooting

Run the doctor command to diagnose issues:

# Interactive diagnostics
funv doctor

# Generate report for support
funv doctor --report

# CI/automation
funv doctor --check-only --json

# Verbose logging
funv new --verbose
funv init --verbose

Common Issues:

• "Access denied": Run funv doctor to check auth, use --fix to auto-repair
• "Authentication failed": Run funv doctor --fix to re-authenticate, or manually run gh auth login (select 'Login with a web browser')
• "GitHub CLI not authenticated": Run gh auth login and select 'Login with a web browser' (NOT 'Paste token')
• Module errors: Run funv doctor --fix to reinstall skill dependencies
• Need help: Run funv doctor --report and share the gist URL

Available Kits

ClaudeKit offers premium starter kits available for purchase at funv.io:

• engineer: ClaudeKit Engineer - Engineering toolkit for building with Claude
• marketing: ClaudeKit Marketing - [Coming Soon]

Each kit provides a comprehensive project template with best practices, tooling, and workflows optimized for Claude Code development.

Configuration

Configuration is stored in ~/.claudekit/config.json:

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

Protected Files

The following file patterns are protected and will not be overwritten during updates:

• .env, .env.local, .env.*.local
• *.key, *.pem, *.p12
• node_modules/**, .git/**
• dist/**, build/**

Excluding Files

Use --exclude flag with glob patterns to skip files:

funv new --exclude "*.log" --exclude "temp/**"
funv update --exclude "node_modules/**" --exclude "dist/**"

Patterns: * (any chars), ** (recursive), ? (single char), [abc], {a,b} Restrictions: No absolute paths, no path traversal (..), 1-500 chars Note: User patterns are ADDED to default protected patterns

Custom .claude Files & Skills Migration

Custom File Preservation: The CLI automatically preserves your custom .claude/ files during updates:

• Custom slash commands
• Personal workflows
• Project-specific configurations
• Any other custom files in .claude/ directory

Skills Directory Migration: Automatic migration when structure changes (flat → categorized):

• Detection: Manifest-based + heuristic fallback
• Customizations: SHA-256 hash comparison detects modifications
• Safety: Backup before migration, rollback on failure
• Preservation: All customizations preserved during migration
• Interactive: Prompts for confirmation (can skip in CI/CD)

Example Migration:

Before (flat):
  .claude/skills/
    ├── gemini-vision/
    ├── postgresql-psql/
    └── cloudflare-dns/

After (categorized):
  .claude/skills/
    ├── ai-multimodal/
    │   └── gemini-vision/
    ├── databases/
    │   └── postgresql-psql/
    └── devops/
        └── cloudflare-dns/

Customizations in any skill are detected and preserved automatically.

Development

See Development Guide for:

• Project structure (modular domain-driven architecture)
• Build & compilation (bun run build, bun run compile)
• Testing & type checking
• Code standards & linting

Architecture Highlights:

• Modular design: 122 focused modules (target: <100 lines each)
• Facade pattern: Each domain exposes public API via facade
• Phase handlers: Complex commands use orchestrator + phase handlers
• Self-documenting names: kebab-case file names describe purpose

Quick Start:

bun install
bun run dev new --kit engineer
bun test

FAQ

Q: Do I need GitHub CLI? A: Yes, GitHub CLI is required. ClaudeKit uses it exclusively for authentication with private repositories.

Q: How do I authenticate? A: Run gh auth login, select 'Login with a web browser', complete OAuth in browser. Do NOT use 'Paste an authentication token'.

Q: "Access denied" error? A: Accept GitHub repo invitation, re-run gh auth login with web browser login, wait 2-5min for permissions.

Q: "GitHub CLI not authenticated" error? A: Run gh auth login and select 'Login with a web browser' (NOT 'Paste token'). PAT authentication is no longer supported.

Q: Is my token secure? A: Yes. GitHub CLI manages tokens securely via OAuth, stored encrypted in OS keychain.

License

MIT