Konek CLI

CLI tool for managing Konek development workflows and kits.

Fast. Simple. Powerful.

Quick Start

# Interactive mode (recommended)
node bin/cli.js init

# Quick install
node bin/cli.js init --kit devkit

# Check version
node bin/cli.js --version

Key Features

✅ Interactive by Default - Menu-driven kit and version selection ✅ 10-40x Faster - Tarball download vs git clone (1-5s vs 20-60s) ✅ Smart Authentication - Auto GitHub CLI login, no manual token setup ✅ Version Selection - Clear stability badges (stable, RC, beta, alpha) ✅ GitHub API - Fast version fetching with caching

Installation

Local Development

cd ~/code/cli.konek.vn
npm install

# Test CLI
node bin/cli.js --version
node bin/cli.js --help

Global Install

# Install globally
npm install -g konek-cli

# Or use with npx (no install needed)
npx konek-cli --version
npx konek-cli init

Commands

Init - Install Kit

Interactive Mode (Default)

node bin/cli.js init

# You'll see:
# ? Select a Kit:
#   ❯ devkit (Konek DevKit - Default development workflows)
#
# ? Select version for devkit:
#   ❯ Latest Stable (v1.16.3) ← recommended
#     v1.16.2 ✓ stable
#     v1.15.0-rc.1 ⚠ RC

Quick Mode

# Install default devkit with default branch
konek init --kit devkit

# Install specific version
konek init --kit devkit --branch v1.16.3

# Global install (to home directory)
konek init --global

# Fresh install (removes existing .claude/)
konek init --fresh

Update - Update Existing Kit

# Interactive mode
konek update

# Quick mode
konek update --kit devkit

CLI Self-Update

# Check for CLI updates
konek cli:update --check

# Update konek-cli to latest version
konek cli:update

Authentication

Automatic (Recommended)

The CLI automatically handles authentication:

1. GitHub CLI - Uses gh auth token if available
2. Environment Variables - Checks GITHUB_TOKEN or GH_TOKEN
3. Auto Login - Offers to run gh auth login for you
4. Manual Token - Fallback to manual token entry

First Time Setup:

# CLI will prompt you
node bin/cli.js init

# If no auth found, you'll see:
# ? Would you like to authenticate with GitHub CLI now? (Y/n)
# Just press Y and follow browser flow!

Manual GitHub CLI Setup

gh auth login
# Follow prompts in browser

Configuration

Config File: .konekrc.json

Optional. Only needed for custom kits.

{
  "version": "1.0",
  "kits": {
    "custom": {
      "repo": "your-org/your-custom-kit",
      "description": "Your Custom Kit",
      "branch": "main"
    }
  }
}

Config file lookup order:

1. --config flag path
2. .konekrc.json in current directory
3. ~/.konekrc.json in home directory
4. Built-in defaults

Built-in Kits

devkit (default)

• Repo: vieterp-vn/devkit.konek.vn
• Description: Konek development workflows

Project Structure

cli.konek.vn/
├── bin/cli.js              # CLI entry point
├── src/
│   ├── commands/           # Command implementations
│   │   ├── init-command.js
│   │   ├── update-command.js
│   │   ├── config-command.js
│   │   ├── doctor-command.js
│   │   └── diagnose-command.js
│   ├── config/             # Config system
│   │   ├── config-loader.js
│   │   ├── config-validator.js
│   │   └── built-in-config.js
│   ├── git/                # GitHub operations
│   │   ├── github-api-lister.js   # Fast version fetching
│   │   ├── tarball-downloader.js  # Fast downloads
│   │   └── index.js
│   ├── auth/               # Authentication
│   │   ├── auth-manager.js
│   │   └── index.js
│   ├── interactive/        # Interactive UI
│   │   ├── prompts.js
│   │   └── index.js
│   ├── kit-registry/       # Kit registry
│   │   ├── kit-registry.js
│   │   └── built-in-kits.js
│   ├── cli-router.js       # Command router
│   └── error-handler.js    # Error handling
├── tests/                  # Test suites
├── CHANGELOG.md            # Version history
└── package.json

Development

Run Tests

npm test                # Run all tests
npm run test:watch      # Watch mode
npm run coverage        # Coverage report

Code Quality

npm run lint            # Check code style
npm run format          # Format code

Performance

| Operation | Time | Details | |-----------|------|---------| | Download | 1-5s | Tarball vs 20-60s git clone (10-40x faster) | | Version Fetch | 0.5-1s | GitHub API vs 3-5s git ls-remote (5-10x faster) | | Total | ~2-6s | Complete installation workflow |

Troubleshooting

Issue: Authentication Failed

Solution: Use GitHub CLI

gh auth login
# Follow browser flow
# Then run: node bin/cli.js init

Alternative: Environment Variable

export GITHUB_TOKEN=your_token
node bin/cli.js init

Issue: Download Failed

Check GitHub access:

# For private repos
gh auth status

# Verify repo exists
gh repo view vieterp-vn/devkit.konek.vn

Issue: .claude Directory Not Found

Make sure your kit repository has .claude/ directory with workflows.

What's New

v1.1.0 - Feature Release (2025-12-01)

New Flags:

• --fresh - Clean install (removes existing .claude directory with confirmation)
• --global - Install to platform-specific home directory (macOS/Linux: ~/, Windows: %USERPROFILE%)

CLI Self-Update:

• konek cli:update - Update konek-cli to latest version
• konek cli:update --check - Check for updates without installing
• Automatic update notifications on CLI startup (cached for 7 days)

Repository Update:

• Default repo changed to vieterp/devkit.konek.vn

v1.0.1 - First Public Release (2025-12-01)

✅ 10-40x Faster Downloads - Tarball download via GitHub API (1-5s vs 20-60s git clone) ✅ 5-10x Faster Version Fetching - GitHub API with 5-minute caching ✅ Auto GitHub Authentication - One-click GitHub CLI integration ✅ Interactive by Default - Menu-driven kit and version selection ✅ Smart Progress Display - Handles unknown file sizes gracefully ✅ Stability Badges - Clear version labeling (stable, RC, beta, alpha)

Architecture:

• GitHub API for fast version fetching and tarball downloads
• Multi-tier authentication (GitHub CLI, env vars, manual entry)
• Native tar extraction with fallback to JS library

License

MIT

Author

Konek Labs

Repository

• Main: vieterp-vn/devkit.konek.vn (private)
• CLI: ~/code/cli.konek.vn (local development)