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.

$3

``bash
npm install -g funv-cli
`

$3

`bash
bun add -g funv-cli
`

$3

`bash
yarn global add funv-cli
`

$3

`bash
pnpm add -g funv-cli
`

After installation, verify it's working:

`bash
ck --version
`

Usage

$3

`bash


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 : Use local archive (zip/tar.gz) instead of downloading
- --kit-path : Use local kit directory instead of downloading

$3

Note: Run from project root.

`bash


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 : Use local archive (zip/tar.gz) instead of downloading
- --kit-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 |

$3

Keep the Funv CLI up to date:

`bash


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

$3

`bash


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
`

$3

`bash


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.

$3

Remove ClaudeKit installations from your system:

`bash
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.

$3

`bash


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
`

$3

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

$3

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

`bash


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/

$3

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:
`bash


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.

$3

`
┌─────────────────────────────────────────────────┐
│ 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) │
└─────────────────────────────────────────────────┘
`

$3

Step 1: Install GitHub CLI
`bash


Windows

winget install GitHub.cli

macOS

brew install gh

Linux

sudo apt install gh
`

Step 2: Authenticate with GitHub CLI
`bash
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:

`bash


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:

`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:

`bash
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

$3

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:
`bash
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