Takumi CLI

Command-line tool for bootstrapping and managing Takumi projects.

Overview

tkm manages Takumi 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/takumi
2. GitHub CLI installed and authenticated: gh auth login
3. Node.js 18+ (runtime) or Bun (development)

Installation

npm install -g @sunasteriskrnd/takumi

Verify: tkm --version

Usage

Quick Start

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

Create New Project

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

Initialize or Update

Run from project root:

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

Update CLI

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

Diagnostics

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

Skills & Agents

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

Other Commands

tkm versions                    # List available versions
tkm migrate                     # Run migration pipeline
tkm uninstall                   # Remove Takumi
tkm config get defaults.kit     # Read config
tkm config set defaults.kit engineer  # Write config

Debugging

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

Authentication

1. Environment Variables (GITHUB_TOKEN, GH_TOKEN)
   ↓ fallback
2. GitHub CLI (gh auth token)

Recommended: gh auth login then authenticate via web browser OAuth.

Configuration

Global config stored in ~/.claude/.takumi.json; project config at <project>/.claude/.takumi.json.

{
  "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.