Spark CLI

A CLI tool for daily dev automation and AI skill integration.

Why Spark? Deterministic tasks (file scaffolding, mirror switching, config management) can be automated by CLI to save token cost. Spark also provides a CLI app backend for AI skills — so agents can call spark instead of burning LLM tokens on repetitive operations.

Most code is AI-generated, all inspired by real daily workflows.

Tech Stack

Layer	Technology
Language	Go 1.25
CLI Framework	Cobra
Config	Viper (~/.spark.yaml)
TUI	PTerm + Bubble Tea
Testing	Ginkgo / Gomega (BDD)
Docs	docmd

Architecture

main.go → cmd.Execute()
├── cmd/                    Cobra command definitions
│   ├── git/                Git repo management commands
│   ├── magic/              System utilities (DNS, mirrors)
│   ├── script/             Script management commands
│   ├── agent.go            AI agent config management
│   ├── agent_profile.go    Agent profile templates
│   └── task.go             Task workflow commands
├── internal/               Business logic by domain
│   ├── agent/              AI agent config (Claude Code, Codex, Kimi, GLM)
│   ├── config/             Config loading & migration
│   ├── git/                Core git operations
│   ├── github/             GitHub API interactions
│   ├── mono/               Mono-repo & submodule management
│   ├── script/             Script discovery & execution
│   ├── task/               Task dispatch/sync/feature CRUD
│   └── tui/                Shared terminal UI components
├── docs/                   Documentation (docmd)
└── scripts/                User-defined automation scripts

Build

make build          # Build + install to ~/.local/bin/spark
make build-linux    # Cross-compile Linux amd64
make build-darwin   # Cross-compile macOS amd64
make test           # Run all unit tests
make test-bdd       # BDD-style tests (Ginkgo)
make lint           # Static analysis (go vet)
make clean          # Remove binary

Run a single test:

go test ./internal/git/... -v -run TestFunctionName

Commands

Global Flags

Flag	Description
--config	Config file (default ~/.spark.yaml)
-p, --path	Directory containing git repos

---

spark git — Git Repository Management

Command	Description
spark git update	Update all repos to latest version
spark git create -n <name> -o <path>	Create mono-repo with submodules
spark git sync <mono-path>	Sync all submodules to latest
spark git gitcode [-p <path>]	Add Gitcode remote to repos
spark git config [--username --email]	Configure git user for repo
spark git url [repo-path]	Get remote URL of repository
spark git batch-clone <account> [--ssh] [--include] [--exclude] [-o <dir>]	Clone all repos from GitHub org/user
spark git update-org-status <org> [--dry-run] [--update-dot-github] [--section <name>]	Update org README with repo list

---

spark agent — AI Agent Configuration

Command	Description
spark agent list	List supported agents
spark agent view <agent>	View agent config files
spark agent edit <agent> [index]	Edit agent config in editor
spark agent reset <agent>	Reset agent config
spark agent profile list	List config profiles
spark agent profile add <name> -t <type>	Add new profile
spark agent profile show <name>	Show profile config
spark agent profile edit <name> [index]	Edit profile config
spark agent use <profile> [-p <dir>]	Apply profile to project
spark agent current [-p <dir>]	Show active profile

Supported agents: claude-code, codex, kimi, glm

---

spark task — Task Management

Command	Description
spark task init	Initialize task directory structure
spark task list	List all tasks and features
spark task create <name> [--content <text>]	Create feature file
spark task delete <name> [--force]	Delete feature file
spark task impl <name>	Implement feature via kimi CLI
spark task dispatch [name] [--dest <path>]	Dispatch task to workspace
spark task sync [name] [--work-path <path>]	Sync task back

Flags: --task-dir, --owner, --work-dir, --tui

---

spark magic — System Utilities

Command	Description
spark magic flush-dns	Flush DNS cache (macOS/Windows/Linux)

Mirror Switching (list / use / current)

Command	Targets
spark magic pip [list|use|current]	Python pip mirrors (tsinghua, aliyun, douban, ustc, tencent)
spark magic go [list|use|current]	Go module proxy (aliyun, tsinghua, goproxy, ustc, nju)
spark magic node [list|use|current]	npm registry (taobao, aliyun, tencent, huawei, ustc)

---

spark script — Custom Scripts

Command	Description
spark script list	List available scripts
spark script run <name> [args...]	Execute a script

Scripts sourced from ~/.spark.yaml (spark.scripts) and scripts/ directory.

Configuration

Config file: ~/.spark.yaml

repo-path:
  - /path/to/repos
git:
  username: your-name
  email: your@email.com
task_dir: /path/to/tasks
github_owner: your-username
work_dir: ./workspace

Documentation

Online docs: https://variableway.github.io/spark-cli/

Path	Content
docs/usage/	Per-command usage guides
docs/analysis/	Architecture & RFC documents
AGENTS.md	AI agent integration guide
CLAUDE.md	Claude Code development guide