Installation

Get DevForgeKit running

Two steps: install the CLI, then run devforgekit install. This page covers everything in between — what you need first, which method to pick for your platform, and what happens after — so a brand-new computer is ready to develop in minutes.

Prerequisites

What you need before installing

DevForgeKit is distributed through package managers, not as a standalone download. Before installing DevForgeKit itself, you need the package manager it's distributed through. These are one-time setup steps.

Node.js 18+ (for npm)

DevForgeKit is distributed through npm, which comes bundled with Node.js. If you don't already have Node.js installed, download the current LTS version from nodejs.org. npm is included automatically, no separate install needed.

Required for: npm install (macOS, Linux, and Windows via WSL)

Homebrew (macOS only)

Homebrew is the package manager used on macOS. If it isn't installed, install it first from brew.sh. DevForgeKit's bootstrap can also provision Homebrew automatically on a factory-fresh Mac.

Required for: Homebrew install (macOS only)

What actually happens

What happens when I install DevForgeKit?

Installing DevForgeKit only installs the DevForgeKit CLI. The CLI is your toolbox. Nothing else is installed until you choose a profile and run devforgekit install. At that point, DevForgeKit installs and configures the development tools you've selected.

Install Node.js
        │
        ▼
npm install -g devforgekit
        │
        ▼
DevForgeKit CLI installed
        │
        ▼
devforgekit install
        │
        ▼
Choose a profile
        │
        ▼
Development tools installed

Platform guide

Which method should I choose?

Do not install Homebrew on Windows; use npm from inside WSL instead. Each platform has one recommended path.

macOS

Certified on Apple Silicon. Intel Macs use the same architecture-detection logic but aren't yet certified on real hardware. The bash bootstrap provisions Homebrew itself on a factory-fresh machine.

Recommended: Homebrew

Alternative: npm

Linux

Certified on Ubuntu and Debian (apt). Fedora (dnf) and Arch (pacman) use the same runtime-detected code paths but aren't yet certified on real hardware.

Recommended: npm

Alternative: Source

Windows

Not supported natively yet - npm install -g devforgekit fails with EBADPLATFORM on stock Windows. Install from inside WSL instead, where winget/choco/scoop are all supported for individual tools.

Recommended: npm (inside WSL)

Alternative: Source (inside WSL)

Step 1

Install the CLI

npm and Homebrew are the recommended way to install. Source is available for contributing or running without a package manager.

On Windows: run this from inside WSL (wsl --install, then open an Ubuntu shell). Running it directly in cmd.exe or PowerShell fails with EBADPLATFORM - the devforgekit command is a bash script and needs a POSIX shell, which stock Windows doesn't have. Native Windows support (no WSL required) is planned for v3.1.

Install: npm

bash

npm install -g devforgekit

devforgekit install

Update

bash

npm update -g devforgekit

Uninstall

bash

npm uninstall -g devforgekit

Verify

bash

devforgekit check

Method guide

Who should use each installation method?

npm

Recommended for:

Windows (from inside WSL - native install isn't supported yet)
Linux
Developers already using Node.js

Homebrew

Recommended for:

macOS
Existing Homebrew users
Apple Silicon and Intel Macs

Source

Recommended for:

Contributors
Developers modifying DevForgeKit
Testing unreleased changes

Important distinction

Installing DevForgeKit vs. running devforgekit install

These are two different things, and it's easy to confuse them the first time.

Installing DevForgeKit

npm install -g devforgekit installs the CLI tool itself. After this, the devforgekit command exists on your machine, but no development tools have been installed yet.

Running devforgekit install

devforgekit install is a separate command you run afterward. It launches the wizard that provisions development tools you actually select: languages, databases, editor extensions, and services.

Brand New Computer
        │
        ▼
Install Node.js
        │
        ▼
npm install -g devforgekit
        │
        ▼
DevForgeKit CLI Installed
        │
        ▼
devforgekit install
        │
        ▼
Development Tools Installed
        │
        ▼
Ready

Fresh machine setup

From a brand-new computer to ready-to-develop

macOS

Brand new Mac

↓

Install Homebrew (brew.sh)

↓

brew install nouradinabdurahman/devforgekit/devforgekit

↓

devforgekit install

↓

Choose profile

↓

Install tools

↓

Ready to develop

Linux

Brand new Linux PC

↓

Install Node.js 18+ (nodejs.org)

↓

npm install -g devforgekit

↓

devforgekit install

↓

Choose profile

↓

Install tools

↓

Ready to develop

Windows

Brand new Windows PC

↓

Install WSL2 (wsl --install)

↓

Inside WSL: install Node.js 18+ (nodejs.org)

↓

Inside WSL: npm install -g devforgekit

↓

devforgekit install

↓

Choose profile

↓

Install tools

↓

Ready to develop

First run

An interactive wizard, not a surprise

Run devforgekit install with no flags in a real terminal and, on a first-ever install, a wizard walks you through exactly what's about to happen instead of silently installing everything. (Building from source instead? The equivalent is ./devforgekit install.)

Minimal, Recommended, Full, or Custom

Custom opens a category checklist (Languages, Databases, Cloud, Containers, Mobile, and more), each with its own description, so you know why a category exists before you check it.

VS Code/Cursor extensions and services

Two separate opt-in prompts: install editor extensions or not, start PostgreSQL/MySQL/Redis or not (or choose exactly which ones).

A real preview before anything installs

Package and cask counts, editor extension count, services, heavy packages flagged with their actual size (e.g. Flutter ~2.1 GB), and a real total download size, measured, never guessed.

Any explicit --profile flag, --yes, --dry-run, or non-interactive/CI use skips the wizard entirely and installs exactly what you asked for. Nothing about scripted or unattended installs changes.

What gets installed

What devforgekit install actually installs

Depending on the profile you choose, DevForgeKit can install and configure tools such as:

Git
Node.js
pnpm
Docker
Flutter
Android Studio
Visual Studio Code
Python
Java
Go
Rust

The exact tools depend on the selected profile. This is why the installation is interactive: DevForgeKit needs to know what you're building before it decides what to install.

Time estimate

Typical installation time

< 1 min

Install DevForgeKit (the CLI itself)

5–30 min

Install development tools, depending on profile and connection speed

Quick start

Your first five minutes

01
Install prerequisite
Node.js (for npm) or Homebrew (for macOS). See Prerequisites below.
02
Install DevForgeKit
npm install -g devforgekit, or the Homebrew equivalent.
03
Verify installation
devforgekit --version confirms the CLI is on your PATH.
04
Run first command
devforgekit install launches the interactive wizard.
05
Choose profile
Minimal, Recommended, Full, or Custom, previewed before anything installs.
06
Install development tools
The wizard provisions languages, databases, editors, and services.
07
Start building
devforgekit opens the dashboard; devforgekit new scaffolds a project.

Quick start

bash

devforgekit --version # verify installation

devforgekit install # provision everything

devforgekit # open the dashboard

devforgekit new nextjs my-app # generate a project

devforgekit doctor # deep diagnostics

Verification

Prove it worked

The installer already does this for you at the end of every run, actually executing devforgekit --version, devforgekit check, and the dashboard fallback path, not just checking that files exist. Run any of these yourself any time:

Verify the installation

bash

devforgekit --version # expect: DevForgeKit 3.0.2

devforgekit check # fast PASS/WARNING/FAIL sweep + health score

devforgekit doctor # deep diagnostics with PATH repair

devforgekit validate # shell, JSON, YAML, Markdown validation

devforgekit repair install # fix a broken symlink, CLI deps, or failed packages

devforgekit --version should print something like DevForgeKit 3.0.2. devforgekit doctor runs a deeper check across your whole environment.

Existing tools

What if I already have these tools installed?

Updates

Keeping DevForgeKit up to date

Update the CLI through whichever channel you installed it with:

Update: npm

bash

npm update -g devforgekit

# or:

npm install -g devforgekit@latest

Update: Homebrew

bash

brew update

brew upgrade devforgekit

Uninstall

Just as easy to remove

devforgekit uninstall shows a checklist (installed packages, VS Code/Cursor extensions, configuration, services) and always previews before removing anything. Configuration files are backed up as <file>.backup-<timestamp> first, never deleted outright.

Uninstall

bash

devforgekit uninstall # interactive checklist in a real terminal

devforgekit uninstall --packages # just the packages it installed

devforgekit uninstall --all --force # everything, non-interactively

Remove the CLI: npm

bash

npm uninstall -g devforgekit

Remove the CLI: Homebrew

bash

brew uninstall devforgekit

Troubleshooting

If something goes sideways

Problem	Fix
A bootstrap step failed	Re-run devforgekit install; every step is idempotent, and a package that failed is offered for resume next time.
A package failed to install	The installer continues past it automatically. Run devforgekit repair install to retry just what failed.
A tool isn't on PATH	devforgekit doctor --fix repairs missing PATH entries.
Services won't start	devforgekit services status shows what's down and why.
Dashboard won't open	Ensure a real TTY, or set DEVFORGEKIT_NO_TUI=1 for classic output.
The devforgekit command is missing or stale	devforgekit repair install recreates the global symlink and reinstalls CLI dependencies.
I want to remove DevForgeKit	devforgekit uninstall previews everything and always asks first.

Check what's actually installed

bash

node --version # Node.js, needed for npm

npm --version # comes bundled with Node.js

brew --version # Homebrew, macOS only

devforgekit --version # DevForgeKit itself

Why doesn't the command work?

The most common first-run confusion. Here's what PATH actually is, in plain English.

What is PATH?

PATH is a list of folders your terminal searches when you type a command. When npm or Homebrew installs devforgekit, it places the command in one of those folders so your shell can find it.

Do I need to edit PATH manually?

Usually not. Both npm and Homebrew add their install locations to PATH automatically during their own setup.

When does DevForgeKit configure PATH automatically?

During devforgekit install, the global command symlink is created for you. If it ever goes missing or stale, devforgekit repair install recreates it, and devforgekit doctor --fix repairs missing PATH entries for tools it installed.

When do I need to restart my terminal?

Right after installing Node.js, npm, or Homebrew for the first time. Your current terminal window loaded PATH when it opened, so it won't see new install locations until you close it and open a new one (or run source ~/.zshrc / the equivalent for your shell).

Roadmap

Future: one-click installers

The whole picture

Architecture overview

DevForgeKit
        │
        ▼
Choose installation method
        │
        ▼
Install CLI
        │
        ▼
Run devforgekit
        │
        ▼
Choose profile
        │
        ▼
Install development tools
        │
        ▼
Ready to develop

Installed? Take the tour.

The features page walks through all fifteen subsystems with real commands.

Install Documentation GitHub

Install Node.js │ ▼ npm install -g devforgekit │ ▼ DevForgeKit CLI installed │ ▼ devforgekit install │ ▼ Choose a profile │ ▼ Development tools installed

Brand New Computer │ ▼ Install Node.js │ ▼ npm install -g devforgekit │ ▼ DevForgeKit CLI Installed │ ▼ devforgekit install │ ▼ Development Tools Installed │ ▼ Ready

Problem

Fix

A bootstrap step failed

Re-run devforgekit install; every step is idempotent, and a package that failed is offered for resume next time.

A package failed to install

The installer continues past it automatically. Run devforgekit repair install to retry just what failed.

A tool isn't on PATH

devforgekit doctor --fix repairs missing PATH entries.

Services won't start

devforgekit services status shows what's down and why.

Dashboard won't open

Ensure a real TTY, or set DEVFORGEKIT_NO_TUI=1 for classic output.

The devforgekit command is missing or stale

devforgekit repair install recreates the global symlink and reinstalls CLI dependencies.

I want to remove DevForgeKit

devforgekit uninstall previews everything and always asks first.

DevForgeKit │ ▼ Choose installation method │ ▼ Install CLI │ ▼ Run devforgekit │ ▼ Choose profile │ ▼ Install development tools │ ▼ Ready to develop