Zup: The Self-Healing CLI That Automates Your Dev Environment

We’ve all been there. You join a new project or onboard a new teammate, and what follows is a painful, multi-hour ritual of cloning repositories, installing a specific version of Node.js, setting up environment variables, running database migrations, and starting a fleet of microservices. It’s tedious, error-prone, and different for every single project.

What if you could automate this entire process with a single command? And what if, when something inevitably goes wrong — a missing dependency, a port conflict, a permission error — the tool could diagnose the problem and fix itself?

That’s why I created Zup.

Zup is a fast, customizable command-line interface (CLI) built with Cobra and Go. It turns complex development environment setups into a simple, repeatable, and resilient process. By defining a sequence of steps in a simple YAML file, you can automate everything from cloning repos to running services. And with its built-in OpenAI integration, Zup can intelligently debug and resolve errors on the fly.

Let’s dive in!

Why Zup?

Zup is designed to solve three core problems with local development setup:

Time & Repetition: Manual setup is a time sink. Zup automates these repetitive tasks, reducing setup time from hours to minutes. Just run zup run, and go grab a coffee. ☕

Inconsistency & “Works on My Machine”: Zup ensures every developer on the team uses the exact same setup process, defined in a zup.yaml file that you can commit to your repository. This eliminates the "it works on my machine" syndrome.

Fragility & Error-Hunting: Traditional scripts are brittle. They break on the first unexpected error, forcing you to decipher cryptic logs and search Stack Overflow. Zup’s self-healing capability is a game-changer. When a command fails, Zup queries OpenAI for a fix, presents it to you, and applies it with your approval.

Getting Started

Prerequisites
You'll need Homebrew installed on your macOS or Linux machine.

Step 1: Install Zup

# Tap into the Zup repository
brew tap devglyph1/zup

# Install the Zup package
brew install zup

Step 2: Configure Your OpenAI API Key

Zup's self-healing magic is powered by AI.

Get your key from the OpenAI API keys page.

Run the following command:

zup set-openai-key

Zup will prompt you to paste your key and will store it securely at $HOME/.zup/config.yaml

How it Works: The zup.yaml File
The heart of Zup is the zup.yaml config file. Here's what a zup.yaml for a full-stack app might look like:

setup:
  - desc: "Starting Docker containers for database and Redis"
    cmd: "docker-compose up -d"
    meta: "This requires Docker Desktop to be running."

  - desc: "Installing backend dependencies"
    cmd: "cd backend-service && go mod tidy && cd .."

  - desc: "Installing frontend dependencies"
    cmd: "cd frontend-app && npm install && cd .."
    meta: "This requires Node.js and npm to be installed. The user might need to use a node version manager like nvm."

  - desc: "Running the backend server on port 8080"
    cmd: "cd backend-service && go run main.go"
    mode: "background"

  - desc: "Running the frontend dev server on port 3000"
    cmd: "cd frontend-app && npm start"
    mode: "background"

Each step has a desc, a cmd, an optional mode (background or same-terminal), and an optional meta field to give the AI extra context for debugging.

Zup Commands

zup run

This is the main command. It reads the zup.yaml file and executes the steps.

zup run

Or specify a path:

zup run --path ./config/dev-setup.yaml

The Self-Healing Workflow
Here's what happens when a command fails:

Execution: Zup tries to run a command, e.g., docker-compose up

Failure: The command fails because Docker isn't running.

Diagnosis: Zup catches the error, sends the failed command, the error message, and meta info to OpenAI.

Suggestion: OpenAI returns a fix (open -a Docker) and an explanation.

Interaction: Zup prints the suggestion to your terminal and asks for approval.

Resolution: You type y, Zup runs the fix, and then automatically re-runs the original docker-compose up command.

Conclusion

Zup has been a game-changer for my workflow. It makes onboarding faster and local development more consistent. I'd love for you to try it out and let me know what you think.

⭐ Star the project on GitHub and check out the code:
https://github.com/devglyph1/homebrew-zup

Happy coding!