v0.5.5: kode init command

New subcommand to bootstrap config files:
  kode init                    Create ./kode.json (local, default)
  kode init --global / -g      Create ~/kode/config.json (global)
  kode init --force / -f       Overwrite existing file

Creates a full template with all fields and sensible defaults.
Prints field descriptions and priority chain on creation.
6 new tests covering local, global, exists, force, short flags, error paths.

Author: jkyberneees

cmd/kode/main.go

@@ -6,6 +6,7 @@ import (
 	"os"
 	"os/exec"
 	"os/signal"
+	"path/filepath"
 	"runtime/debug"
 	"strings"
 
@@ -54,6 +55,11 @@ func main() {
 		}
 	case "version":
 		fmt.Println("kode", getVersion())
+	case "init":
+		if err := initConfig(os.Args[2:]); err != nil {
+			fmt.Fprintf(os.Stderr, "kode: %v\n", err)
+			os.Exit(1)
+		}
 	default:
 		fmt.Fprintf(os.Stderr, "kode: unknown command %q\n", os.Args[1])
 		printUsage()
@@ -127,9 +133,19 @@ done:
 func printUsage() {
 	fmt.Println(`Usage:
   kode run [flags] <task>
+  kode init [--global | -g] [--force | -f]
   kode version
 
-Flags:
+Commands:
+  run                 Execute a task with the agent loop
+  init                Create a config file (default: ./kode.json)
+  version             Print version and exit
+
+Init flags:
+  --global, -g        Create global config at ~/kode/config.json
+  --force, -f         Overwrite existing file without prompting
+
+Run flags:
   --model <name>       LLM model (default: deepseek-chat)
                        Known profiles: deepseek-v4-flash, deepseek-v4-pro
                        Profiles auto-set thinking/timeout defaults.
@@ -161,6 +177,81 @@ Environment variables:
   KODE_SYSTEM          System prompt override`)
 }
 
+// ── Init ──────────────────────────────────────────────────────────────
+
+const defaultConfigTemplate = `{
+  "model": "deepseek-v4-flash",
+  "base_url": "https://api.deepseek.com/v1",
+  "api_key": "${DEEPSEEK_API_KEY}",
+  "thinking": "",
+  "max_iterations": 90,
+  "sandbox": false,
+  "no_color": false,
+  "no_agents": false,
+  "system": ""
+}`
+
+func initConfig(args []string) error {
+	global := false
+	force := false
+
+	for i := 0; i < len(args); i++ {
+		switch args[i] {
+		case "--global", "-g":
+			global = true
+		case "--force", "-f":
+			force = true
+		default:
+			return fmt.Errorf("unknown flag %q for init", args[i])
+		}
+	}
+
+	var configPath string
+	var scope string
+	if global {
+		configPath = config.GlobalConfigPath()
+		scope = "global"
+	} else {
+		configPath = config.ProjectConfigPath()
+		scope = "local"
+	}
+
+	// Check if file already exists
+	if _, err := os.Stat(configPath); err == nil && !force {
+		fmt.Fprintf(os.Stderr, "kode: %s config already exists at %s\n", scope, configPath)
+		fmt.Fprintf(os.Stderr, "  Use --force to overwrite.\n")
+		return nil
+	}
+
+	// Create parent directory (os.MkdirAll on "." is a no-op — fine for local)
+	dir := filepath.Dir(configPath)
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return fmt.Errorf("create directory %s: %w", dir, err)
+	}
+
+	if err := os.WriteFile(configPath, []byte(defaultConfigTemplate+"\n"), 0644); err != nil {
+		return fmt.Errorf("write config: %w", err)
+	}
+
+	fmt.Printf("✓ Created %s config: %s\n", scope, configPath)
+	fmt.Println()
+	fmt.Println("  Edit this file to set your preferences. Available fields:")
+	fmt.Println("    model           LLM model name")
+	fmt.Println("    base_url        API endpoint URL")
+	fmt.Println("    api_key         API key (supports ${VAR} substitution)")
+	fmt.Println("    thinking        Reasoning depth (enabled/disabled/low/medium/high)")
+	fmt.Println("    max_iterations  Max think->act cycles")
+	fmt.Println("    sandbox         Run in Docker sandbox (true/false)")
+	fmt.Println("    no_color        Disable colored output (true/false)")
+	fmt.Println("    no_agents       Skip AGENTS.md (true/false)")
+	fmt.Println("    system          System prompt override")
+	fmt.Println()
+	fmt.Println("  Priority: config file < KODE_* env < CLI flags")
+	return nil
+}
+
+// ── Run ───────────────────────────────────────────────────────────────
+
 // run executes the `kode run` command and returns an error on failure.
 // The caller is responsible for printing the error and calling os.Exit.
 func run(args []string) error {

cmd/kode/main_test.go

@@ -196,7 +196,9 @@ func TestPrintUsage(t *testing.T) {
 
 	required := []string{
 		"kode run",
+		"kode init",
 		"kode version",
+		"Commands:",
 		"--model",
 		"Known profiles",
 		"deepseek-v4-flash",
@@ -209,6 +211,8 @@ func TestPrintUsage(t *testing.T) {
 		"--no-color",
 		"--no-agents",
 		"--system",
+		"--global",
+		"--force",
 		"~/kode/config.json",
 		"KODE_MODEL",
 		"KODE_API_KEY",
@@ -621,3 +625,134 @@ func dockerAvailable() bool {
 	_, err := exec.LookPath("docker")
 	return err == nil
 }
+
+// ── Init Config Tests ─────────────────────────────────────────────────
+
+func TestInitConfig_Local(t *testing.T) {
+	dir := t.TempDir()
+	cwd, _ := os.Getwd()
+	os.Chdir(dir)
+	defer os.Chdir(cwd)
+
+	origHome := os.Getenv("HOME")
+	os.Setenv("HOME", t.TempDir()) // isolate from any global config
+	defer os.Setenv("HOME", origHome)
+
+	if err := initConfig([]string{}); err != nil {
+		t.Fatalf("initConfig() error: %v", err)
+	}
+
+	// Verify the file was created
+	data, err := os.ReadFile("kode.json")
+	if err != nil {
+		t.Fatalf("kode.json not created: %v", err)
+	}
+	content := string(data)
+	if !strings.Contains(content, "deepseek-v4-flash") {
+		t.Errorf("config should contain deepseek-v4-flash, got: %s", content)
+	}
+	if !strings.Contains(content, "api_key") {
+		t.Errorf("config should contain api_key field, got: %s", content)
+	}
+}
+
+func TestInitConfig_Global(t *testing.T) {
+	dir := t.TempDir()
+	origHome := os.Getenv("HOME")
+	os.Setenv("HOME", dir)
+	defer os.Setenv("HOME", origHome)
+
+	if err := initConfig([]string{"--global"}); err != nil {
+		t.Fatalf("initConfig() --global error: %v", err)
+	}
+
+	// Verify the file was created
+	data, err := os.ReadFile(dir + "/kode/config.json")
+	if err != nil {
+		t.Fatalf("global config not created: %v", err)
+	}
+	content := string(data)
+	if !strings.Contains(content, "deepseek-v4-flash") {
+		t.Errorf("config should contain deepseek-v4-flash, got: %s", content)
+	}
+}
+
+func TestInitConfig_LocalExists(t *testing.T) {
+	dir := t.TempDir()
+	cwd, _ := os.Getwd()
+	os.Chdir(dir)
+	defer os.Chdir(cwd)
+
+	origHome := os.Getenv("HOME")
+	os.Setenv("HOME", t.TempDir())
+	defer os.Setenv("HOME", origHome)
+
+	// Create existing config
+	os.WriteFile("kode.json", []byte(`{"model": "existing"}`), 0644)
+
+	// Should warn, not overwrite
+	if err := initConfig([]string{}); err != nil {
+		t.Fatalf("initConfig() error: %v", err)
+	}
+
+	// Content should be unchanged
+	data, _ := os.ReadFile("kode.json")
+	if !strings.Contains(string(data), "existing") {
+		t.Error("config should not have been overwritten")
+	}
+}
+
+func TestInitConfig_LocalForce(t *testing.T) {
+	dir := t.TempDir()
+	cwd, _ := os.Getwd()
+	os.Chdir(dir)
+	defer os.Chdir(cwd)
+
+	origHome := os.Getenv("HOME")
+	os.Setenv("HOME", t.TempDir())
+	defer os.Setenv("HOME", origHome)
+
+	// Create existing config
+	os.WriteFile("kode.json", []byte(`{"model": "old"}`), 0644)
+
+	// Force overwrite
+	if err := initConfig([]string{"--force"}); err != nil {
+		t.Fatalf("initConfig() --force error: %v", err)
+	}
+
+	// Content should be the template
+	data, _ := os.ReadFile("kode.json")
+	if strings.Contains(string(data), "old") {
+		t.Error("config should have been overwritten")
+	}
+	if !strings.Contains(string(data), "deepseek-v4-flash") {
+		t.Errorf("config should contain template, got: %s", string(data))
+	}
+}
+
+func TestInitConfig_UnknownFlag(t *testing.T) {
+	err := initConfig([]string{"--unknown"})
+	if err == nil {
+		t.Fatal("expected error for unknown flag")
+	}
+	if !strings.Contains(err.Error(), "unknown flag") {
+		t.Errorf("error should mention unknown flag, got: %v", err)
+	}
+}
+
+func TestInitConfig_ShortFlags(t *testing.T) {
+	// Test -g and -f short flags
+	dir := t.TempDir()
+	origHome := os.Getenv("HOME")
+	os.Setenv("HOME", dir)
+	defer os.Setenv("HOME", origHome)
+
+	if err := initConfig([]string{"-g", "-f"}); err != nil {
+		t.Fatalf("initConfig() -g -f error: %v", err)
+	}
+
+	// Verify
+	if _, err := os.Stat(dir + "/kode/config.json"); err != nil {
+		t.Errorf("global config should exist after -g -f: %v", err)
+	}
+}