isetup 1.2.1

Cross-platform CLI tool for one-click dev environment setup.

isetup

Last synced with code: 2026-04-10 · 62 tools · 8 profiles · Go 1.22+

中文文档

Cross-platform CLI tool that detects your OS, hardware, and architecture, then adaptively runs the right install commands to one-click deploy your dev environment.

CLI-only tools. isetup is designed for command-line engineers. The default template includes only terminal-based tools — no GUI applications.

New machine? isetup install. Done.

Features

• Auto-detection — OS, architecture, distro, GPU, available package managers, shell
• Multi-platform — macOS, Linux (Ubuntu/Fedora/Arch), Windows, WSL
• Profile-based config — group tools by use case (00-base, 01-lang-runtimes, 02-git-tools, 03-python-dev, 04-ai-tools, 05-shell-enhancements, 06-system-tools, 07-gpu)
• Adaptive install — automatically picks brew, apt, choco, winget, dnf, pacman, or custom shell scripts based on what's available
• Root / Docker aware — auto-detects UID 0 and omits sudo so installs work inside containers without sudo installed
• Template variables — {{.Arch}}, {{.OS}}, {{.Home}} in shell commands for arch-aware downloads
• Dependency ordering — depends_on ensures tools install in the right order
• Conditional profiles — when: has_gpu skips GPU tools on machines without a GPU
• Skip installed — auto-detects tools already in PATH, skips them (use -f to force reinstall)
• Rich diagnostics — full command output, environment snapshot, and timing in ~/.isetup/logs/
• Real-time progress — [N/Total] counter with system info header, no silent waiting
• Dry-run mode — preview all commands without executing

Install

Via pip (cross-platform, no Go toolchain required):

pip install isetup

The wheel bundles a matching pre-built binary; pip picks the right one for your OS/arch. Works inside a virtualenv or pipx.

Easiest (if Go is installed):

go install github.com/host452b/isetup@latest

One-liner (Linux / macOS):

curl -fsSL https://raw.githubusercontent.com/host452b/isetup/main/install.sh | bash

Custom install directory:

INSTALL_DIR=~/.local/bin curl -fsSL https://raw.githubusercontent.com/host452b/isetup/main/install.sh | bash

Windows (PowerShell):

$version = (Invoke-RestMethod "https://api.github.com/repos/host452b/isetup/releases/latest").tag_name.TrimStart('v')
$url = "https://github.com/host452b/isetup/releases/download/v$version/isetup_${version}_windows_amd64.zip"
Invoke-WebRequest $url -OutFile isetup.zip
Expand-Archive isetup.zip -DestinationPath .
Move-Item -Force isetup.exe "$env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\"
Remove-Item isetup.zip

From source:

git clone https://github.com/host452b/isetup.git && cd isetup && go build -o isetup .

Verify:

isetup version

Quick Start

# Generate default config (optional — isetup works without it)
isetup init

# Edit your config
vim ~/.isetup.yaml

# Preview what will be installed
isetup install --dry-run

# Install everything
isetup install

# Install specific profiles only
isetup install -p 00-base,04-ai-tools

Interactive Mode

Run isetup install -i (or just isetup install in a TTY with no other flags) to pick tools with arrow keys.

isetup install · interactive mode                    linux/amd64 · apt,pip,npm

[x] ▼ 00-base                                           14/14 selected
      [x] curl                  apt
      [x] git                   apt
      [ ] neovim                apt
[x] ▶ 01-lang-runtimes                                   7/ 7 selected
[ ] ▶ 04-ai-tools                                        0/ 7 selected
[·] ✗ 07-gpu                    no GPU detected          0/ 2 (disabled)

─────────────────────────────────────────────────────────────────────────────
↑/↓ move · Space toggle · →/← expand/collapse · Enter confirm · q quit · ? help

Keys:

Key	Action
↑ / ↓ / k / j	Move cursor
→ / l	Expand profile
← / h	Collapse profile; from a tool row, jump to parent profile
Space	Toggle selection (on a profile: all selectable children at once)
Enter	Go to confirmation page
Y / Enter on confirm	Start install
E on confirm	Return to picker, preserving selection
q / Esc / Ctrl+C	Exit without installing
?	Toggle help overlay

Defaults on open:

• Profiles whose when: condition is satisfied on the current system → selected, collapsed.
• Profiles whose when: is unmet (e.g., has_gpu on a laptop) → disabled (cannot be toggled).
• Tools with no install method on the current system → unchecked, shown with ⚠ no method.

Dependencies are resolved at confirm time: selecting claude-code automatically pulls in node-lts, nvm, and curl — they appear on the confirm page under "Required dependencies".

The interactive flow opts out when stdin isn't a TTY (CI, curl | bash) or when any install flag is passed (-p, -f, --dry-run). To force interactive inside a TTY even with those flags, pass -i explicitly.

Default Tools

The built-in template installs 62 tools across 8 profiles:

lang-runtimes — Language Runtimes & Version Managers

Tool	Description
nvm	Node.js version manager — switch between Node versions per project
node-lts	Node.js LTS release, installed via nvm
typescript	TypeScript compiler (tsc)
golang	Go programming language
rust	Rust toolchain via rustup (rustc, cargo, rustfmt)
miniconda	Conda package/env manager — auto_activate_base disabled, use conda activate manually
mise	Polyglot runtime manager (asdf replacement, manages Node/Python/Go/etc. versions)

base — Core CLI Essentials

Editor & Terminal

Tool	Description
git	Distributed version control
neovim	Modern terminal editor (Vim fork)
tmux	Terminal multiplexer — split panes, detach sessions
tmux-ide	Scripted tmux session layouts (npm)

Search & Navigation

Tool	Description
fzf	Fuzzy finder — interactive filter for files, history, branches
ripgrep	Recursive grep replacement (rg), extremely fast
fd	Simpler, faster find alternative with sane defaults
tree	Visualize directory structure as a tree

Modern CLI Replacements (Rust-powered)

Tool	Description
bat	cat replacement with syntax highlighting and Git integration
eza	ls replacement with icons, colors, and Git status

Data Processing

Tool	Description
glow	Terminal Markdown reader — TUI browser, remote file rendering
jq	Command-line JSON processor — parse API responses, transform configs
yq	YAML/TOML/XML processor — edit CI configs, K8s manifests

System Utilities

Tool	Description
htop	Interactive process viewer and system monitor
btop	Resource monitor with rich TUI (CPU, memory, disk, network)
make	Build automation — many repos ship a Makefile by default
curl	URL data transfer (HTTP client, API testing)
wget	File downloader with resume support
zip	Compression utility
unzip	Decompression utility
fonts-firacode	Fira Code programming font with ligatures

git-tools — Git & CI/CD

Tool	Description
gh	GitHub CLI — PRs, issues, actions, repos from terminal
glab	GitLab CLI — MRs, pipelines, issues from terminal
lazygit	Terminal UI for git — staging, branching, rebasing visually
delta	Git diff pager with syntax highlighting and side-by-side view
gitlab-runner	GitLab CI runner — run CI jobs locally, manage runners

python-dev — Python Ecosystem

Tool	Description
uv	Ultra-fast Python package installer (pip replacement)
pip-tools	httpie (HTTP client), black (formatter), ruff (linter)
pip-build-tools	build, twine, hatchling — Python package publishing
huggingface-hub	Hugging Face CLI — download/upload models and datasets
pr-analyzers	gitlab-pr-analyzer, github-pr-analyzer, jira-lens
playwright	Browser automation for testing (Chromium/Firefox/WebKit)
pgcli	PostgreSQL CLI with auto-completion and syntax highlighting
ai-ml-libs	chromadb (vector DB), pgvector, langsmith, langfuse (LLM observability)
casts-down	Podcast download + Whisper transcription CLI

ai-tools — AI & LLM

Tool	Description
claude-code	Anthropic Claude Code — AI coding assistant in terminal
codex-cli	OpenAI Codex CLI — AI code generation
cursor	Cursor AI editor (CLI installer)
yoyo	PTY proxy for AI agent auto-approve workflows
arxs	Multi-source academic paper search CLI (go install preferred, shell fallback)
ollama	Run LLMs locally (Llama, Mistral, etc.)
llama-cpp	High-performance C++ LLM inference (llama-cli, llama-server)

gpu — NVIDIA GPU (conditional: when: has_gpu)

Tool	Description
cuda-toolkit	NVIDIA CUDA compiler and libraries
nvidia-driver	NVIDIA driver v550

shell-enhancements — Shell Productivity

Tool	Description
zoxide	Smarter cd — learns your most-used directories
starship	Cross-shell prompt with git status, language versions, minimal config
direnv	Auto-load .envrc per directory — manage env vars per project

system-tools — Debugging & Networking

Tool	Description
lsof	List open files and ports — find what's using port 8080
netcat	TCP/UDP Swiss Army knife — test connections, port scanning
tcpdump	Network packet capture and analysis
dnsutils	DNS lookup tools: dig, nslookup
strace	Trace system calls — debug process behavior (Linux only)
sqlite3	SQLite database CLI — lightweight DB queries and debugging
net-tools	Classic network commands: ifconfig, netstat, route
speedtest-cli	Network speed test from the terminal (speedtest-cli --simple)

Commands

isetup init                      Generate default ~/.isetup.yaml
isetup init --force              Overwrite existing config
isetup detect                    Print detected system info as JSON
isetup install                   Install all profiles
isetup install -p 00-base,04-ai-tools  Install specific profiles
isetup install -f                Reinstall even if already installed
isetup install --dry-run         Preview commands without executing
isetup install --timeout 5m     Set per-tool timeout (default 10m)
isetup list                      List all profiles and tools
isetup version                   Print version

Configuration

Config lives at ~/.isetup.yaml (override with --config).

version: 1

settings:
  log_level: info
  dry_run: false

profiles:
  00-base:
    tools:
      - name: curl
        apt: curl
        brew: curl

      - name: git
        apt: git
        dnf: git
        pacman: git
        brew: git
        choco: git

  01-lang-runtimes:
    tools:
      - name: nvm
        depends_on: curl
        shell:
          unix: "curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash"

      - name: node-lts
        depends_on: nvm
        shell:
          unix: "source ~/.nvm/nvm.sh && nvm install --lts"

      - name: golang
        brew: go
        depends_on: curl
        shell:
          linux: |
            GO_VERSION=$(curl -fsSL "https://go.dev/VERSION?m=text" | head -1)
            TMPFILE=$(mktemp /tmp/go-XXXXXX.tar.gz)
            curl -fsSL "https://go.dev/dl/${GO_VERSION}.linux-{{.Arch}}.tar.gz" -o "$TMPFILE"
            sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf "$TMPFILE"
            rm -f "$TMPFILE"

  04-ai-tools:
    tools:
      - name: claude-code
        depends_on: node-lts
        shell:
          unix: "curl -fsSL https://claude.ai/install.sh | bash"

      - name: arxs
        depends_on: golang
        shell:
          unix: |
            if command -v go >/dev/null 2>&1; then
              go install github.com/host452b/arxs/v2@latest
            else
              curl -fsSL https://raw.githubusercontent.com/host452b/arxs/main/install.sh | sh
            fi

  07-gpu:
    when: has_gpu
    tools:
      - name: cuda-toolkit
        apt: nvidia-cuda-toolkit

See template/default.yaml for the full 61-tool configuration.

Install Methods

Each tool can declare multiple install methods. isetup picks the best one for the current system:

Key	Expands to	Platform
apt: X	sudo apt install -y X (fallback: apt-get)	Linux (Debian/Ubuntu) — sudo omitted when root
dnf: X	sudo dnf install -y X	Linux (Fedora/RHEL) — sudo omitted when root
pacman: X	sudo pacman -S --noconfirm X	Linux (Arch) — sudo omitted when root
brew: X	brew install X	macOS
choco: X	choco install X -y	Windows (priority)
winget: X	winget install --id X -e --accept-source-agreements	Windows (fallback)
pip: [X, Y]	pip3 install X Y	Any (conda pip preferred)
npm: X	npm install -g X	Any (requires Node.js)
shell:	Custom commands per OS	Any

Shell Priority

shell.linux / shell.darwin / shell.windows  (exact OS match)
  → shell.unix                               (linux + darwin fallback)
    → shell (string shorthand)               (unix only)

Template Variables

Shell commands support Go template interpolation:

Variable	Example value
{{.Arch}}	x86_64, aarch64, arm64
{{.OS}}	linux, darwin, windows
{{.Distro}}	Ubuntu 22.04.3 LTS
{{.Home}}	/home/user

Conditions

Condition	Meaning
when: has_gpu	Skip profile if no GPU detected

Logging

Logs are written to ~/.isetup/logs/ (override with --log-dir).

Each run produces two files:

• isetup-<timestamp>.env.json — environment snapshot (OS, arch, GPU, pkg managers — no sensitive env vars)
• isetup-<timestamp>.log — per-tool install record with command, stdout, stderr, exit code, duration

Example terminal output:

Detecting system...
OS: linux | Arch: amd64 | Shell: /bin/bash
Package managers: apt, pip3, npm
GPU: NVIDIA H200 NVL

[1/61] Installing nvm (shell: curl -o- https://nvm.sh/install.sh | bash)...
[1/61] nvm                  PASS    (shell ) 0.7s
[2/61] Installing node-lts (shell: source ~/.nvm/nvm.sh && nvm install --lts)...
[2/61] node-lts             PASS    (shell ) 0.5s
[3/61] git                  SKIP    already installed
[4/61] Installing glab (shell: curl ... | sudo bash)...
[4/61] glab                 PASS    (shell ) 2.1s
[5/61] cuda-toolkit         FAILED  (apt   ) 1.1s
       E: Unable to locate package nvidia-cuda-toolkit

─────────────────────────────
Installed: 50 | Failed: 1 | Skipped: 6
Log: ~/.isetup/logs/isetup-2026-03-25T00-04-21.log

Output is color-coded: green for PASS, red for FAILED, yellow for SKIP. First line of stderr is shown inline for failed tools.

System Detection

isetup detect outputs full system info as JSON:

{
  "os": "darwin",
  "arch": "arm64",
  "arch_label": "arm64",
  "distro": "macOS 15.3.2",
  "kernel": "24.3.0",
  "wsl": false,
  "is_root": false,
  "shell": "/bin/zsh",
  "gpu": {
    "detected": true,
    "model": "Apple M3 Pro"
  },
  "pkg_managers": ["brew", "pip3", "npm"]
}

Project Structure

isetup/
├── main.go                  # Entry point
├── embed.go                 # Embeds default template
├── cmd/                     # CLI commands (cobra)
├── internal/
│   ├── config/              # YAML parsing + validation
│   ├── detector/            # OS/GPU/shell/pkg manager detection
│   ├── executor/            # Install engine (bootstrap, resolver, runner, topo sort)
│   └── logger/              # Structured logging
└── template/
    └── default.yaml         # Default config template

Install Flow

What happens when you run curl -fsSL ... | bash or isetup install:

┌─────────────────────────────────────────────────────────────┐
│  curl -fsSL .../install.sh | bash                            │
│  → downloads isetup binary                                   │
│  → prints getting-started hints (does NOT auto-run install) │
└───────────────────────────┬─────────────────────────────────┘
                            │  user runs:  isetup install  (or -i)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  1. DETECT SYSTEM                                            │
│     OS, arch, distro, GPU, shell, package managers          │
│     → SystemInfo struct                                      │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  2. LOAD CONFIG                                              │
│     ~/.isetup.yaml → parse YAML → validate                  │
│     (if no config: use embedded default.yaml)               │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  3. BOOTSTRAP (minimal containers only)                      │
│     Missing curl/wget/ca-certificates/gnupg?                │
│     → apt update && apt install -y ...                       │
│     → fallback: apt-get if apt fails                        │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  4. COLLECT & SORT TOOLS                                     │
│     Profiles sorted alphabetically (00-base → 07-gpu)       │
│     Topological sort by depends_on                          │
│     → ordered tool list                                      │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  5. FOR EACH TOOL:                                           │
│                                                              │
│     ┌── already in PATH?  → SKIP                            │
│     ├── depends_on failed? → SKIP                           │
│     ├── when: condition not met? → SKIP                     │
│     └── resolve install method:                             │
│         shell.linux > apt > dnf > pacman > pip > npm        │
│                                                              │
│     Execute command (timeout: 10m default)                   │
│     If apt fails → retry with apt-get                       │
│     If root → strip sudo from commands                      │
│                                                              │
│     Log: stdout, stderr, exit code, duration                │
│     Report: PASS / FAIL / SKIP                              │
│                                                              │
│     On FAIL:                                                 │
│       • Print first 3 lines of stderr                       │
│       • Print retry command (copy-pasteable)                │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  6. SUMMARY                                                  │
│     Installed: N | Failed: N | Skipped: N                   │
│     Log: ~/.isetup/logs/isetup-<timestamp>.log              │
│                                                              │
│     If failures:                                             │
│       • List all failed tools with retry commands           │
│       • "Tip: paste to AI assistant for diagnosis"          │
└─────────────────────────────────────────────────────────────┘

Install Method Resolution (per tool)

Has shell.linux / shell.darwin / shell.windows?
  → YES: use it (highest priority — exact OS match)
  → NO: check shell.unix fallback
         → YES: use it (linux + darwin)
         → NO: try package managers:
                apt → apt-get (fallback) → dnf → pacman → brew → choco → winget
                → pip (conda pip > pip3 > pip)
                → npm
                → no method found: SKIP

Troubleshooting

Tool install hangs: Use --timeout 2m to set a shorter per-tool timeout. Check ~/.isetup/logs/ for the full command output.

Minimal container (no curl/wget): isetup auto-detects missing prerequisites (curl, wget, ca-certificates, gnupg) and installs them via apt/apt-get before running any profiles. Works out-of-the-box in bare ubuntu:22.04 Docker containers.

Permission denied: isetup auto-detects root and omits sudo. If you're not root and sudo fails, ensure your user has sudo privileges.

Profile not found: Check available profiles with isetup list. Profile names are case-sensitive.

Already installed tools: isetup skips tools found in PATH. Use -f to force reinstall.

Custom config location: Use --config /path/to/config.yaml to point to a non-default config file.

Exit Codes

Code	Meaning
0	All tools installed or skipped successfully
1	One or more tools failed to install
2	Configuration error (invalid YAML, validation failure)

Build

go build -o isetup .

Requires Go 1.22+.

Documentation

Document	Description
README.md	This file — features, install, usage, flow diagram
README_zh.md	Chinese documentation
CHANGELOG.md	Version history with all changes
CONTRIBUTING.md	How to add tools and submit PRs
SECURITY.md	Security policy and vulnerability reporting
CLAUDE.md	Project rules for AI agents (coding conventions)
template/default.yaml	Full 62-tool configuration (the source of truth)

License

MIT