vikit-cli

CLI for bootstrapping, updating, and managing vikit projects. Includes a local web dashboard (vk config) for configuration.

⚠️ Breaking Change — Core / Premium Split

vk init and vk new now install only the FREE core set (9 skills + 2 agents) offline, with no GitHub authentication. Premium skills/agents are no longer installed by default.

• Who is affected: anyone reinstalling, setting up a new machine, or recovering an install. Existing on-disk content is preserved — but a fresh vk init will no longer pull the full premium bundle for free.
• This is intentional (no grandfathering). To get the full bundle again, purchase at https://vikit.cc and install with vk install <bundle>.
• Power users are unaffected: --archive, --kit-path, and --use-git still target any source you choose.

See Breaking Changes — Core/Premium Split for full details.

Overview

vikit Config UI (vk) provides both CLI and web dashboard for managing vikit projects. It is built with Bun, TypeScript, and React for development, while the published CLI runs on plain Node.js so end users do not need Bun installed.

Key Features:

• CLI Commands (16): new, init, config, projects, setup, skills, agents, commands, migrate, doctor, versions, update, uninstall, watch, content, easter-egg
• Web Dashboard: Interactive React UI via vk config ui for configuration and project management
• Hook Diagnostics Dashboard: Inspect recent Claude hook activity and failures from vk config across global and project scopes
• Projects Registry: Centralized registry at ~/.vikit/projects.json with file locking
• Skill Installation: Install vikit skills to other coding agents (Cursor, Codex, etc.)
• Multi-tier Authentication: gh CLI → env vars → keychain → prompt fallback
• Smart Merging: Conflict detection with user customization preservation
• Skills Migration: Auto-detects and migrates skills structure changes
• Offline Installation: From local archives or directories
• Security: Path traversal protection, symlink validation, UNC path protection
• Cross-Platform: macOS, Linux, Windows with platform-specific optimizations
• Update Notifications: Intelligent 7-day cache for version checks

Prerequisites

• Node.js ≥ 18.0.0
• GitHub CLI (gh) installed and authenticated (gh auth login — select "Login with a web browser")

See Authentication for full gh setup.

Breaking Changes — Core/Premium Split

Starting with this version, vk init / vk new ship and install the free core set embedded inside the npm package — fully offline, zero network calls, no gh auth required. This is the instant-value teaser for the premium bundle.

| | Before | After | |---|---|---| | Default vk init source | Full engineer kit (GitHub Release, requires gh auth) | Embedded free core (offline, no auth) | | Premium skills/agents | Installed for free by default | Not installed — purchase required | | --archive / --kit-path / --use-git | Power-user overrides | Unchanged — still target any source |

The free core set (9 skills + 2 agents): vk-ask, vk-docs-seeker, vk-coding-level, vk-git, vk-journal, vk-sequential-thinking, vk-project-organization, vk-find-skills, vk-scout, plus agents vk-docs-manager and vk-researcher.

Why this is intentional (no grandfathering)

This is a retroactive paywall by design. There is no grandfather flag and no automatic detection of prior installs — reinstalling, moving machines, or recovering an install will land you on core-only. We chose prominent, honest messaging over silent partial installs.

• Existing on-disk content is never deleted. This change only affects what a fresh vk init/vk new installs.
• First-run hint: until you complete a successful install, the CLI prints a one-time hint explaining the split and the purchase path. It disappears afterward.
• To restore the full bundle: purchase at https://vikit.cc, then run vk install <bundle>.

Migration notes

• If you already have the full kit installed and do not reinstall: no action needed. Your files are untouched.
• If you reinstall / new machine / recover: expect core-only by default. Use vk install <bundle> after purchasing, or pass --archive/--kit-path/--use-git to install from a specific source.
• CI / automation: non-interactive and non-TTY runs suppress the first-run hint, so pipelines are unaffected.

Installation

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

End-user runtime note: global installs from npm, pnpm, yarn, or bun all execute the packaged Node.js CLI. Bun is optional for users and only needed for local vikit CLI development workflows.

Using npm (Recommended)

npm install -g vikit-cli

Using Bun

bun add -g vikit-cli

Using Yarn

yarn global add vikit-cli

Using pnpm

pnpm add -g vikit-cli

After installation, verify it's working:

vk --version

Usage

Discoverability Quick Start

# Top-level command discovery
vk --help

# Open config dashboard immediately
vk config

# Expose the dashboard intentionally to your LAN/Tailscale
vk config --host 0.0.0.0 --no-open

# Command-level help (recommended)
vk config --help
vk skills --help
vk agents --help
vk commands --help
vk migrate --help

Config Dashboard Access

By default, vk config binds the dashboard to 127.0.0.1 for local-only access.

Use --host when you intentionally want remote access from another device on the same trusted network:

# Bind to all interfaces
vk config --host 0.0.0.0 --no-open

# Bind to a specific interface or hostname
vk config --host 100.88.12.4 --no-open
vk config --host dashboard.local --no-open

The dashboard still enforces same-origin browser access. Remote access works when you open the UI from the same host/origin that reaches the server, instead of relying on a hardcoded IP allowlist.

Create New Project

# Interactive mode
vk new

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

# Show beta versions
vk new --beta

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

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

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

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

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

Flags:

• --install-skills: Auto-install Python packages, system tools (FFmpeg, ImageMagick), Node.js packages
• --prefix: Move commands to /vk: namespace (/plan → /vk: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.

⚠️ Default changed: vk init now installs the free core set offline (no gh auth) instead of the full premium bundle. See Breaking Changes. Use --archive/--kit-path/--use-git to install from a specific source, or vk install <bundle> after purchasing.

# Interactive mode
vk init

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

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

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

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

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

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

# Offline installation (from local archive or directory)
vk init --archive ~/downloads/engineer-v1.16.0.zip
vk 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 /vk: 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 vikit | engineer (first option) | | Target directory | Current directory (.) | | Version selection | Latest stable release | | Google Gemini setup | Skip | | Other optional features | Skip |

Update CLI

Keep the vikit CLI up to date:

# Check for CLI updates
vk update --check

# Update to latest version
vk update

# Update to specific version
vk update --version 1.1.0

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

The CLI notifies you when updates are available via vk --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 the engineer kit
vk versions

# Filter by specific kit
vk versions --kit engineer

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

# Include prereleases and drafts
vk versions --all

Diagnostics & Doctor

# Full health check (default)
vk doctor

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

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

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

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

# Machine-readable JSON output
vk doctor --json

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

Health Checks:

• System: Node.js, npm, Python, pip, Claude CLI, git, gh CLI
• vikit: 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 vk 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: vk diagnose is deprecated. Use vk doctor instead.

Uninstall

Remove vikit installations from your system:

vk uninstall              # Interactive mode - prompts for scope and confirmation
vk uninstall --local      # Uninstall only local installation (current project)
vk uninstall --global     # Uninstall only global installation (~/.claude/)
vk uninstall -l -y        # Local only, skip confirmation
vk uninstall -g -y        # Global only, skip confirmation
vk 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 vikit installations
• Use --local or --global flags to skip the prompt

What it does:

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

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

Watch GitHub Issues (vk watch)

Autonomous daemon that monitors GitHub issues, analyzes them with Claude, generates plans, and creates PRs.

# Start watching (single repo)
vk watch

# Dry-run mode (no posts/PRs)
vk watch --dry-run

# Custom poll interval (ms)
vk watch --interval 60000

# Force restart (clear state)
vk watch --force

# Verbose logging
vk watch --verbose

Features: issue lifecycle management (10 statuses), Claude-powered brainstorming/planning, automatic PR creation, rate limiting (persisted across restarts), maintainer reply filtering, processedIssues TTL, optional git worktree isolation per issue, multi-repo support, graceful shutdown.

Config: .vk.json under watch key. Run vk watch --help for full configuration reference.

Content Generation (vk content)

Daemon that scans git activity (commits, PRs, tags), generates social media content with Claude, and publishes to X/Twitter and Facebook.

# Interactive setup wizard
vk content setup

# Start daemon
vk content start

# Check status
vk content status

# View logs
vk content logs

# Queue manual content
vk content queue

# Review workflow
vk content approve <id>
vk content reject <id>

# Dry-run / verbose
vk content start --dry-run
vk content start --verbose

Features: 11-phase pipeline (scan → filter → classify → context → create → validate → review → photo → publish → engage → analyze), noise filtering, context caching (24h TTL), content validation, photo generation, 3 review modes (auto/manual/hybrid), quiet hours scheduling, engagement tracking, SQLite database, platform-specific adapters.

Config: .vk.json under content key. Run vk content --help for full configuration reference.

Other Commands

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

# Show help
vk --help
vk -h

# Command-specific help
vk new --help
vk init --help
vk config --help
vk skills --help
vk versions --help

Debugging

vk new --verbose              # Enable verbose logging
vk new --verbose --log-file debug.log  # Save to file
VIKIT_VERBOSE=1 vk 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)
VK_CACHE_TTL=7200 vk versions    # Cache for 2 hours
VK_CACHE_TTL=0 vk versions       # Disable caching (always fetch fresh)

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

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

Update Notifications

The vk --version command checks for newer versions of your installed vikit 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 vk --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: ~/.vikit/cache/version-check.json (Windows: %USERPROFILE%\.vikit\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 (~/.vikit/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
vk doctor

# Generate report for support
vk doctor --report

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

# Verbose logging
vk new --verbose
vk init --verbose

Common Issues:

• "Access denied": Run vk doctor to check auth, use --fix to auto-repair
• "Authentication failed": Run vk 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 vk doctor --fix to reinstall skill dependencies
• Need help: Run vk doctor --report and share the gist URL

Available Kits

vikit will offer premium starter kits at vikit.cc (coming soon):

• engineer: vikit Engineer - Engineering toolkit for building with Claude (v1.0.0+)

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

Configuration

Configuration is stored in ~/.vikit/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:

vk new --exclude "*.log" --exclude "temp/**"
vk 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.

FAQ

Q: Do I need GitHub CLI? A: Yes, GitHub CLI is required. vikit 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.

Support

For questions, feedback, or bug reports, email [email protected].

A public support hub at vikit.cc is coming soon.

License

MIT

This project is inspired from speckit and superpowers, used under the MIT License