Installing Command Line Tools on a Headless Mac.

It all started as a simple maintenance check that turned into hours of troubleshooting.
While auditing our macOS build servers, I found one in a remote data center running an outdated Xcode Command Line Tools version. Normally, that’s a quick fix—unless the machine is headless, has no GUI or Apple ID, and xcode-select --install fails because it needs a graphical prompt.
So I had to figure out how to update Xcode tools entirely over SSH—no screen, no clicks. Here’s how I solved it (and hopefully save you a few hours too).

A Quick Note on DMG and PKG Files

macOS software often comes packaged in two common formats: DMG and PKG. A DMG is a disk image—essentially a virtual drive that you mount to access its contents, similar to opening an ISO file on Linux. Inside, you'll usually find a PKG, which is the actual installer package containing the files and scripts needed for installation.

In this guide, we'll mount the DMG containing Apple's Command Line Tools and then extract or transfer the PKG for installation on a headless Mac.

Background / Why GUI is sometimes needed

• Apple officially distributes CLT (Command Line Tools) as a DMG file (Command_Line_Tools_for_Xcode_26.dmg).
• DMGs are normally mounted as volumes using hdiutil, which may require a GUI session to function correctly.
• On headless Macs, hdiutil attach fails because there's no GUI environment.
• Therefore, to get the actual .pkg installer from a DMG, you should:
  1. Mount the DMG on a Mac with GUI.
  2. Copy (via scp) the .pkg to the headless Mac.
• Once the .pkg is on the headless Mac, installation can proceed entirely via CLI.

Step 1: Extract the .pkg on a GUI Mac

Apple provides a .pkg version that can be installed entirely from the command line:

1. Go to: https://developer.apple.com/download/all/
2. Sign in with your Apple ID.
3. Search for "Command Line Tools for Xcode" for your macOS version.
4. Download the .pkg file (e.g., Command_Line_Tools_for_Xcode_26.x.dmg).
5. Mount the DMG:
   Assuming the .dmg is downloaded to ~/Downloads:

$ hdiutil attach ~/Downloads/Command_Line_Tools_for_Xcode_26.x.dmg

You should see something similar to this:

hdiutil attach ~/Downloads/Command_Line_Tools_for_Xcode_26.dmg
Checksumming Protective Master Boot Record (MBR : 0)…
Protective Master Boot Record (MBR :: verified   CRC32 $8D68846E
Checksumming GPT Header (Primary GPT Header : 1)…
 GPT Header (Primary GPT Header : 1): verified   CRC32 $69483B4F
Checksumming GPT Partition Data (Primary GPT Table : 2)…
GPT Partition Data (Primary GPT Tabl: verified   CRC32 $37626EC5
Checksumming  (Apple_Free : 3)…
                    (Apple_Free : 3): verified   CRC32 $00000000
Checksumming disk image (Apple_HFS : 4)…
.............................................................................................................................
          disk image (Apple_HFS : 4): verified   CRC32 $6621D134
Checksumming  (Apple_Free : 5)…
..............................................................................................................................................
                    (Apple_Free : 5): verified   CRC32 $00000000
Checksumming GPT Partition Data (Backup GPT Table : 6)…
GPT Partition Data (Backup GPT Table: verified   CRC32 $37626EC5
Checksumming GPT Header (Backup GPT Header : 7)…
  GPT Header (Backup GPT Header : 7): verified   CRC32 $922B7862
verified   CRC32 $86C0BB44
/dev/disk2              GUID_partition_scheme
/dev/disk2s1            Apple_HFS                       /Volumes/Command Line Developer Tools

• This will mount the DMG under /Volumes/Command Line Developer Tools/(or similar).

6. Locate the .pkg inside:

$ ls "/Volumes/Command Line Developer Tools"

You should see:

Command Line Tools.pkg

Step 2: Transfer the .pkg to your headless Mac

Use scp from the GUI Mac:

$ scp "/Volumes/Command Line Developer Tools/Command Line Tools.pkg"  user@headless-mac:/tmp/

• Replace user@headless-mac with your headless Mac's SSH credentials.
• The file will be placed in /tmp/ on your headless Mac.

Step 3: Detach Mounted DMGs on the GUI

— that's an important step!
When you mount the DMG on your GUI Mac it creates a virtual volume (like /Volumes/Command Line Developer Tools). After copying the PKG, you must detach it to free system resources:

$ hdiutil detach "/Volumes/Command Line Developer Tools"

Why it matters:

• Leaving it mounted can cause file locks, consume RAM, and may interfere with other DMG mounts.
• If you forget, the volume persists in /Volumes/, and subsequent commands may fail or copy from the wrong location.

Step 4: Install the .pkg on your headless Mac

SSH into your headless Mac and run:

$ sudo installer -pkg /tmp/Command\ Line\ Tools.pkg -target /

• This installs CLT into /Library/Developer/CommandLineTools.

Step 5: Switch active developer directory

$ sudo xcode-select --switch /Library/Developer/CommandLineTools

This tells macOS to use the Command Line Tools (CLT) instead of expecting full Xcode.
It sets /Library/Developer/CommandLineTools as the active toolchain so commands like gcc → the C compiler, make → build automation orgit → version control work system-wide.

Step 6: Verify installation

run:

$ xcode-select -p

# Should output: /Library/Developer/CommandLineTools

as well as:

gcc --version
make --version
git --version

# Should ouput their respective version#

• These commands should work, confirming that CLT is functional.

It's a small reminder that not every "simple update" plays nice — yet with curiosity, persistence, and command-line discipline, even Apple’s GUI-centric tools can be managed entirely from afar.

Every hurdle you overcome adds to your knowledge and confidence.
That's it. We hope this guide has been helpful and inspires you to tackle tricky updates with patience and creativity!