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 auth login                  # One-time login (default install path)
tkm init                        # Initialize/update in current project (interactive)
tkm init --kit core             # Initialize with a specific kit
tkm init -g -y                  # Global install, non-interactive

The default tkm init / versions flows download releases through the authenticated Takumi server (no gh CLI required). Run tkm auth login once before the first install. The legacy GitHub flow is still available via --use-gh for archived tags.

Initialize / Update Project

tkm init is the sole entry point — it creates a missing target directory automatically and works equally for new projects and updates of existing ones. Run from a project root (or with --dir):

tkm init                                # Interactive (claude-code default)
tkm init -y                             # Non-interactive, latest version
tkm init --dir my-project --kit core    # Create new project at ./my-project
tkm init -g --kit core -y               # Global install
tkm init --fresh                        # Clean reinstall (destructive)
tkm init --install-skills               # Auto-install skill deps
tkm init --archive ~/kit.zip            # Offline install
tkm init --local                        # From local monorepo (development)
tkm init -a codex                       # Install only codex agents/commands/skills
tkm init -a claude-code codex           # Install both (sequential)

--sync is currently claude-code-only; combining --sync with any other agent is rejected with a clear error.

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

Install to Other Coding Agents

tkm init -a codex --kit core        # Install for Codex
tkm init -a claude-code -a codex        # Install for multiple agents

Other Commands

tkm versions                    # List available versions
tkm uninstall                   # Remove Takumi
tkm config get defaults.kit     # Read config
tkm config set defaults.kit core  # Write config

Debugging

tkm init --verbose                       # Verbose logging
tkm init --verbose --log-file debug.log  # Save to file
TAKUMI_VERBOSE=1 tkm init                # 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": "core", "dir": "." }
}

Protected Files

Never overwritten during updates: .env*, *.key, *.pem, node_modules/**, .git/**, dist/**

Development

bun install                    # Install deps
bun run dev init --kit core # 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.