Team Onboarding Setup Guide

Xcode Command Line Tools prerequisite

Apple's compiler toolchain. Git ships inside it, and Homebrew requires it.

You did not pick this one. It is here because homebrew needs it first.

macOS

Run xcode-select --install and click Install in the dialog that appears.
```
xcode-select --install
```
Wait. This is several hundred megabytes and takes 5 to 10 minutes. There is no progress detail, so a slow download looks like a hang. It is not.
Expect a long wait
Nothing on screen changes for minutes at a time. Leave it alone.

Done when a path ending in CommandLineTools or Xcode.app.

xcode-select -p

Homebrew prerequisite

The package manager most macOS developer tooling assumes exists.

You did not pick this one. It is here because postgres needs it first.

macOS

Open brew.sh and copy the install command from the top of that page. Copy it from their page, not from this one: it is long, and a curl | bash line broken across a line break is both wrong and alarming.
Copy from brew.sh
This is the one command in this guide you should not copy from here.
When it finishes, the installer prints a Next steps block with two or three shellenv commands. Run what your own screen prints. The path differs depending on your chip, so it will not match anyone else's.
Do not skip this
Skipping the Next steps block is the most common Homebrew failure. brew is then 'command not found' in every new terminal.
Open a new terminal window before continuing.

Done when a version number.

brew --version

Linux

Open brew.sh and copy the install command from the top of that page.
Run the shellenv lines the installer prints when it finishes, then open a new terminal.

Done when a version number.

brew --version

VS Code

The editor. It goes first because Git's Windows installer asks which editor to use.

macOS

Download from code.visualstudio.com, unzip, and drag Visual Studio Code.app into Applications.
Open the command palette with Cmd+Shift+P, run Shell Command: Install 'code' command in PATH, and confirm.
This step gets skipped
Without it, code does nothing in a terminal, and the failure shows up much later as a confusing error in a different step.

Done when three lines: version, commit hash, architecture.

code --version

Windows

Download from code.visualstudio.com. The default button gives you the User Installer, which needs no administrator rights.
On the Select Additional Tasks screen, confirm Add to PATH is checked. It usually is, but not always.
Check the box
If it is unchecked, the failure surfaces much later as 'code' is not recognized.

Done when three lines: version, commit hash, architecture.

code --version

Linux

Take the .deb or .rpm from code.visualstudio.com, or add the Microsoft apt/dnf repository if you want it to update with the rest of your system.

Done when three lines: version, commit hash, architecture.

code --version

Extensions worth adding by name, because search results are full of near-duplicates: Python (Microsoft), ESLint, Prettier.

Git

Version control. Install it after your editor, before anything that clones.

macOS

Git comes with the Command Line Tools. Run git --version and let the install dialog appear if it has not already.
```
git --version
```

Set your identity. The email has to match a verified email on your GitHub account.

git config --global user.name "Your Full Name"
git config --global user.email "you@example.com"

Set what the Windows installer sets for you.

git config --global core.editor "code --wait"
git config --global init.defaultBranch main

Done when a version number.

git --version

Windows

Run the installer from git-scm.com. It is roughly 14 screens. Four of them need changing and the rest are already correct.
Default editor — change it from Vim to VS Code. This is the most important screen in the installer.
If you land in Vim anyway
Press Esc, type :q!, press Enter. Vim gives no visible way out and this traps people for a long time.
Initial branch name — override it to main, to match GitHub.
PATH environment — keep the recommended middle option.
Credential helper — keep Git Credential Manager. It opens a browser to log into GitHub instead of asking for a password you do not have.

Set your identity. The email has to match a verified email on your GitHub account.

git config --global user.name "Your Full Name"
git config --global user.email "you@example.com"

Done when a version number.

git --version

Linux

Install the distro package: sudo apt install git, or your distribution's equivalent.

Set your identity. The email has to match a verified email on your GitHub account.

git config --global user.name "Your Full Name"
git config --global user.email "you@example.com"

Done when a version number.

git --version

GitHub CLI

GitHub from the terminal: authentication, pull requests, repository operations.

macOS

Install it with Homebrew.
```
brew install gh
```
Log in and follow the browser flow.
```
gh auth login
```

Done when your GitHub username, and 'Logged in to github.com'.

gh auth status

Windows

Install it with winget.
```
winget install --id GitHub.cli
```
Open a new terminal, then log in and follow the browser flow.
```
gh auth login
```

Done when your GitHub username, and 'Logged in to github.com'.

gh auth status

Linux

Install it from your package manager, or follow the instructions at cli.github.com.
Log in and follow the browser flow.
```
gh auth login
```

Done when your GitHub username, and 'Logged in to github.com'.

gh auth status

nvm

A Node version manager. Install this instead of installing Node directly, so a project needing a different Node version is a one-line change rather than a reinstall.

macOS

Open github.com/nvm-sh/nvm and copy the install command from its README. Copy it from there rather than from here: the command has a version number in the URL, so a printed one goes stale and installs an old nvm.
Open a new terminal. The installer appends a block to your shell profile, and it does not apply to the terminal you ran it in.
New terminal required
Without one, nvm is not found and the install looks like it failed.

Install the current LTS and make it the default.

nvm install --lts
nvm use --lts
nvm alias default lts/*

The alias default line matters. Without it, every new terminal starts with the system Node, or none at all, and it looks like nvm did not work.

Done when an nvm version, then a Node version.

nvm --version
node --version

Windows

Uninstall any existing Node.js first, from Add or remove programs.
Do this before anything else
An existing Node install sits earlier on your PATH. nvm use then reports success while the old Node stays active, and you get a version manager that silently does nothing.
Download nvm-setup.exe from github.com/coreybutler/nvm-windows/releases and run it.
This is a different project
Windows nvm is coreybutler/nvm-windows, by a different author. Its commands differ from every nvm tutorial written for macOS or Linux.
Right-click your terminal and choose Run as administrator, then install the current LTS. Note the syntax: no double dashes.
```
nvm install lts
nvm use lts
```
nvm use needs the administrator terminal, because it works by rewriting a symlink. In a normal terminal it fails in a way that does not obviously say 'run me as admin'.

Done when an nvm version, then a Node version.

nvm version
node --version

Linux

Open github.com/nvm-sh/nvm and copy the install command from its README.
Open a new terminal, then install the current LTS and make it the default.
```
nvm install --lts
nvm use --lts
nvm alias default lts/*
```

Done when an nvm version, then a Node version.

nvm --version
node --version

uv

One tool covering Python interpreters, virtual environments and packages.

macOS

Install it with Homebrew, or with the script on docs.astral.sh/uv.
```
brew install uv
```
Get an interpreter.
```
uv python install
```

Done when a version number.

uv --version

Windows

Install it with winget, or with the script on docs.astral.sh/uv.
```
winget install --id astral-sh.uv
```
Open a new terminal, then get an interpreter.
```
uv python install
```

Done when a version number.

uv --version

Linux

Install it with the script on docs.astral.sh/uv.
Open a new terminal, then get an interpreter.
```
uv python install
```

Done when a version number.

uv --version

Day to day: uv init starts a project, uv venv makes an environment, uv add <pkg> installs into it.

Node.js

The JavaScript runtime.

Handled by nvm

You installed nvm, so Node came with it. There is nothing to install here, and on Windows installing Node separately would actively break nvm. Just confirm the version.

macOS

From nodejs.org, take the LTS button on the left, not Current on the right. The .pkg, all defaults.

Done when two version numbers.

node --version
npm --version

Windows

From nodejs.org, take the LTS button on the left, not Current on the right.
Run the .msi. Leave 'Tools for Native Modules' unchecked.
Leave that box alone
Checking it launches a PowerShell window that downloads Chocolatey, Python and Visual Studio Build Tools. Twenty minutes or more, frequently fails, rarely needed.

Allow npm to run scripts, then confirm the change stuck.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
Get-ExecutionPolicy -Scope CurrentUser

Done when two version numbers.

node --version
npm --version

Linux

Use the NodeSource repository, or a version manager. The distro package is usually well behind.

Done when two version numbers.

node --version
npm --version

Python

The Python interpreter.

Handled by uv

You installed uv, which manages interpreters itself, so there is nothing to install from python.org. Installing one anyway leaves two Pythons on the machine, which is the top cause of 'it works in the terminal but not in my editor'.

macOS

Take the .pkg from python.org/downloads.
Open the installed folder in Applications and double-click Install Certificates.command.
Do not skip this
Skipping it produces an SSL error later that is genuinely hard to trace back to here.

Done when a version number.

python3 --version

Windows

Take the large button at the top of python.org/downloads.
On the first installer screen, tick Add python.exe to PATH. It is at the bottom of the screen and it is unchecked by default.
The single most consequential checkbox
If you miss it: re-run the installer, choose Modify, and enable PATH. You do not need to uninstall anything.

Done when a version number.

py --version

Linux

It is usually already there. Check with python3 --version before installing anything.

Done when a version number.

python3 --version

Which word you type matters. py on Windows, python3 on macOS and Linux. Bare python opens the Microsoft Store on Windows and usually does not exist on macOS.

Docker

Containers. This one is a large download and wants a restart, so it is late on purpose.

macOS

Download Docker Desktop from docker.com and install it. Choose the build matching your chip, Apple Silicon or Intel.
Launch Docker Desktop once and wait for the whale icon in the menu bar to stop animating. The command line does not work until it has.

Done when "Hello from Docker!" and a short explanation.

docker run hello-world

Windows

Download Docker Desktop from docker.com and install it. It will install WSL2 if you do not have it.
Expect a restart
WSL2 requires one. Save your work before you start this step.
After the restart, launch Docker Desktop once and wait for it to report Engine running.

Done when "Hello from Docker!" and a short explanation.

docker run hello-world

Linux

Install Docker Engine following the instructions for your distribution at docs.docker.com/engine/install.
Add yourself to the docker group so you do not need sudo for every command, then log out and back in.
```
sudo usermod -aG docker $USER
```

Done when "Hello from Docker!" and a short explanation.

docker run hello-world

PostgreSQL

A client-server relational database. Two checks, not one: a version check only proves the client program exists.

macOS

Install it with Homebrew, pinning the major version so a later brew upgrade cannot move the data directory out from under you.
```
brew install postgresql@18
```
Start it. This is a separate step and it is the one people skip.
```
brew services start postgresql@18
```
Installing is not starting
Homebrew installs the service and leaves it stopped. brew services list shows whether it is actually running.

Done when a version number, then a row of server version detail.

psql --version
psql -d postgres -c "select version();"

Windows

Run the installer from enterprisedb.com. It bundles pgAdmin, which is worth keeping.
Partway through it asks for a superuser password. Write it down now.
There is no recovery path
If you lose this password there is no way to recover it later. Put it in your password manager before you click Next.
Leave the port at 5432 unless something already has it.

Done when a version number, then a row of server version detail.

psql --version
psql -d postgres -c "select version();"

Linux

Install and enable it.

sudo apt install postgresql
sudo systemctl enable --now postgresql

On Debian and Ubuntu the install creates a postgres system user, so your first connection is usually sudo -u postgres psql rather than a bare psql.

Done when a version number, then a row of server version detail.

psql --version
psql -d postgres -c "select version();"

The first check proves the client exists. The second proves the server is running and reachable, which is the thing you actually need.

Check your work

Every check for what you selected, in one place. Run them in a new terminal.

macOS

Xcode Command Line Tools
```
xcode-select -p
```
a path ending in CommandLineTools or Xcode.app
Homebrew
```
brew --version
```
a version number
VS Code
```
code --version
```
three lines: version, commit hash, architecture
Git
```
git --version
```
a version number
GitHub CLI
```
gh auth status
```
your GitHub username, and 'Logged in to github.com'
nvm
```
nvm --version
node --version
```
an nvm version, then a Node version
uv
```
uv --version
```
a version number
Node.js
```
node --version
npm --version
```
two version numbers
Python
```
python3 --version
```
a version number
Docker
```
docker run hello-world
```
"Hello from Docker!" and a short explanation
PostgreSQL
```
psql --version
psql -d postgres -c "select version();"
```
a version number, then a row of server version detail

Windows

VS Code
```
code --version
```
three lines: version, commit hash, architecture
Git
```
git --version
```
a version number
GitHub CLI
```
gh auth status
```
your GitHub username, and 'Logged in to github.com'
nvm
```
nvm version
node --version
```
an nvm version, then a Node version
uv
```
uv --version
```
a version number
Node.js
```
node --version
npm --version
```
two version numbers
Python
```
py --version
```
a version number
Docker
```
docker run hello-world
```
"Hello from Docker!" and a short explanation
PostgreSQL
```
psql --version
psql -d postgres -c "select version();"
```
a version number, then a row of server version detail

Linux

Homebrew
```
brew --version
```
a version number
VS Code
```
code --version
```
three lines: version, commit hash, architecture
Git
```
git --version
```
a version number
GitHub CLI
```
gh auth status
```
your GitHub username, and 'Logged in to github.com'
nvm
```
nvm --version
node --version
```
an nvm version, then a Node version
uv
```
uv --version
```
a version number
Node.js
```
node --version
npm --version
```
two version numbers
Python
```
python3 --version
```
a version number
Docker
```
docker run hello-world
```
"Hello from Docker!" and a short explanation
PostgreSQL
```
psql --version
psql -d postgres -c "select version();"
```
a version number, then a row of server version detail

When it goes wrong

Indexed by what is on your screen, not by topic. Use your browser's find (Ctrl/Cmd+F) and paste the error text.

The install dialog fails partway through

macOS Xcode Command Line Tools

Remove the partial install and start again: sudo rm -rf /Library/Developer/CommandLineTools, then re-run xcode-select --install.

zsh: command not found: brew

macOS Linux Homebrew

The Next steps block was skipped. Re-run the installer to print it again, run those lines, then open a new terminal.

An install takes an hour and prints compiler output

macOS Homebrew

Prebuilt bottles only exist for recent macOS versions. On an older one Homebrew builds from source. It usually still works, but budget the time.

'code' is not recognized

Windows VS Code

Add to PATH was unchecked during install. Re-run the installer; it preserves your other settings.

zsh: command not found: code

macOS VS Code

The shell command was never installed. Cmd+Shift+P, then Shell Command: Install 'code' command in PATH.

Your commits show up on GitHub as someone else, or as no one

macOS Windows Linux Git

user.email does not match a verified email on your GitHub account. Nothing errors when this is wrong, which is why it goes unnoticed. Fix it with git config --global user.email and check github.com/settings/emails.

Filename too long

Windows Git

Run git config --global core.longpaths true. This bites on Node projects in particular.

You clicked past one of the four screens that mattered

Windows Git

Re-run the installer. It is safe, and it preserves the settings you already made.

which nvm finds nothing

macOS Linux nvm

This is expected. nvm is a shell function, not a binary, so which cannot see it. Use command -v nvm instead: it prints nvm when things are working.

nvm: command not found

macOS Linux nvm

You are still in the terminal you ran the installer in. Open a new one.

nvm use succeeds but node --version is unchanged

Windows nvm

An older Node install is still on your PATH. Uninstall it from Add or remove programs, then run nvm use lts again in an administrator terminal.

exit status 1: Access is denied

Windows nvm

nvm use needs an administrator terminal. Right-click your terminal and choose Run as administrator.

Code runs in the terminal but the editor shows import errors

macOS Windows Linux uv

The editor is pointed at a different Python. In VS Code, run Python: Select Interpreter from the command palette and choose the one inside your project's .venv folder.

npm cannot be loaded because running scripts is disabled on this system

Windows Node.js

Run Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned, then Get-ExecutionPolicy -Scope CurrentUser to confirm. On a managed laptop the change is sometimes silently overridden; if so, use Command Prompt instead of PowerShell, where npm works unchanged.

EACCES: permission denied when installing a global package

macOS Linux Node.js

Do not reach for sudo npm install -g. It creates root-owned files in your home directory that break later installs in confusing ways. Use a version manager instead, which puts everything under your own account.

Typing python opens the Microsoft Store

Windows Python

That is a stub Microsoft ships. Use py instead. To remove the stub permanently: Settings → Apps → Advanced app settings → App execution aliases, and turn off python.exe and python3.exe.

It reports Python 2

macOS Linux Python

You reached a system Python. Use python3.

SSL: CERTIFICATE_VERIFY_FAILED

macOS Python

Install Certificates.command was never run. Open the Python folder in Applications and double-click it.

Cannot connect to the Docker daemon

macOS Windows Linux Docker

Docker is installed but not running. On macOS and Windows, launch Docker Desktop and wait for it to finish starting. On Linux, sudo systemctl start docker.

An image runs but is noticeably slow

macOS Docker

On Apple Silicon, x86 images run under emulation. Look for an arm64 tag of the image, or accept the slower run.

database "yourname" does not exist

macOS Windows Linux PostgreSQL

psql with no arguments tries to connect to a database named after your OS user. Nothing is wrong. Use psql -d postgres instead.

could not connect to server: Connection refused

macOS Linux PostgreSQL

The server is not running. macOS: brew services start postgresql@18. Linux: sudo systemctl start postgresql.

Port 5432 is already in use

macOS Windows Linux PostgreSQL

Something else has it, usually an older Postgres install or a Docker container. The error does not say which. docker ps first, then look for an existing service.

How this page was made

The dependency graph driving the install order is scripts/order-tools.js, imported directly at build time, so this demo cannot show an order the skill would not produce. Run it yourself:

node scripts/order-tools.js postgres node docker --os macos

The prose is an authored example, the way real output is: the skill writes it from references/tool-catalog.md, which holds source material and traps rather than finished steps.

Build your copy

Share this configuration

Install order

Steps

macOS

macOS

Linux

macOS

Windows

Linux

macOS

Windows

Linux

macOS

Windows

Linux

macOS

Windows

Linux

macOS

Windows

Linux

macOS

Windows

Linux

macOS

Windows

Linux

macOS

Windows

Linux

macOS

Windows

Linux

Check your work

macOS

Windows

Linux

When it goes wrong

How this page was made