# Install the CLI

> Install the simforge command line on Linux, macOS or Windows and check the machine with simforge doctor.

Source: https://simforge.ai/docs/install

`simforge` is a single binary for Linux, macOS and Windows. It contains no engine or renderer: those come with the runtime, a separate download after you [sign in](/docs/sign-in).

Linux and macOS:

```sh
curl -fsSL https://simforge.ai/install.sh | sh
```

Windows (PowerShell):

```powershell
irm https://simforge.ai/install.ps1 | iex
```

Use these terminal installation commands. The current CLI binaries are not signed with a macOS Developer ID or Windows Authenticode certificate, so browser-downloaded, quarantined copies are not qualified for Gatekeeper or SmartScreen. Do not disable operating-system security or change PowerShell execution policy to run a downloaded installer file.

The installer picks the build for your machine, downloads it, checks the archive's and the binary's sha256, and installs `simforge`: into `~/.local/bin` on Linux and macOS, into `%LOCALAPPDATA%\SimForge\bin` on Windows (set `SIMFORGE_INSTALL_DIR` to change either). It reads no credentials. `install.sh` edits no shell files: when `~/.local/bin` is not on your `PATH` it prints the line to add (for zsh, the macOS default, to `~/.zshrc`). `install.ps1` adds its folder to your user `PATH`. When it finishes it prints the next steps: [sign in](/docs/sign-in), accept the agreement, install the runtime, and install `ffmpeg`, which renders need to write their videos (`sudo apt-get install ffmpeg` on Ubuntu, `brew install ffmpeg` on macOS, `winget install Gyan.FFmpeg` on Windows).

## Check the install

```sh
simforge --version
```

Then [sign in](/docs/sign-in). From there, two paths:

- **Cloud only.** Add `--cloud` to commands and they run on SimForge's machines; this machine needs no runtime, GPU or ffmpeg. `simforge auth status` checks the sign-in. See [Run in the cloud](/docs/cloud).
- **On this machine.** [Install the runtime](/docs/sign-in#install-the-runtime), then check the machine with `simforge doctor`.

To pin a published runtime release, use `simforge runtime install --version VERSION --accept-license`. This selects the runtime version; `simforge --version` reports the CLI version.

## Check the machine

```sh
simforge doctor
```

`simforge doctor` runs in the runtime, so it needs the runtime installed; before that it stops with `runtime_not_installed` and says what to do. It checks the machine: the GPU adapter, ffmpeg, the cache folders, free disk and whether the map registry can be reached. Each check reports `ok`, or what is missing and how to fix it. A machine without a GPU gets a warning, not a failure: simulation and 2D renders run on the CPU. Pass `--offline` to skip the network check; it is then reported as skipped, never as ok.

## What the machine needs

| | Linux | macOS | Windows |
|---|---|---|---|
| CLI and `--cloud` | x86_64, glibc 2.39 or newer (Ubuntu 24.04 or later) | macOS 13 or later, Apple silicon or Intel | Windows 10 (1803) or 11, x64 or Arm64 |
| Local runtime: simulation, 2D | x86_64 | Apple silicon or Intel | x64 |
| Local 3D and schematic | NVIDIA, Vulkan, 8 GiB, driver 570 or newer | Apple M3 or newer with 16 GB of memory or more | NVIDIA, Vulkan, 8 GiB, driver 570 or newer |

- On Windows on Arm the CLI runs every command with `--cloud`; a local command stops with `runtime_platform_unsupported` and says so. An Intel Mac runs simulation and 2D renders locally and 3D with `--cloud`.
- Outside the 3D column, render commands stop with `gpu_unsupported`, `gpu_memory_unsupported` or `gpu_driver_unsupported` before any work. An Apple silicon Mac gives three quarters of its memory to the GPU, so a 16 GB Mac renders with 512 px textures and 24 GB or more with full textures. 2D rendering and simulation run on the CPU everywhere.
- Video encodes with `ffmpeg` (libx264) on macOS and Windows; the NVIDIA hardware encoder is used on Linux. GPU lidar needs Vulkan ray queries, so on macOS lidar uses the CPU reference.
- `ffmpeg` with libx264 on the `PATH` to encode videos: `sudo apt-get install ffmpeg` (Ubuntu), `brew install ffmpeg` (macOS), `winget install Gyan.FFmpeg` (Windows), or point `SIMFORGE_FFMPEG_BINARY` at one. `simforge doctor` checks it and prints the command; without it renders still write their frames and warn `video_encoder_missing`.
- Disk for the runtime and the maps you download. The runtime is about 2.7 GB and a map with its 3D environment 5–19 GB.

## Running in Docker

Run the container with the NVIDIA container runtime and its graphics capability, and install the EGL and OpenGL libraries in the image:

```sh
docker run --runtime nvidia -e NVIDIA_DRIVER_CAPABILITIES=graphics,compute,utility ...
apt-get install -y libegl1 libgl1        # in the image
```

Plain `--gpus all` exposes the GPU for compute only: Vulkan cannot start, and 3D and schematic renders fail with `render_failed`. 2D renders and simulation need no GPU in the container.

## Remove it

Run `simforge logout` first if you also want to sign this machine out and delete its stored tokens.

Linux and macOS:

```sh
curl -fsSL https://simforge.ai/install.sh | sh -s -- --uninstall
```

Windows (PowerShell):

```powershell
& ([scriptblock]::Create((irm https://simforge.ai/install.ps1))) -Uninstall
```

Use the same `SIMFORGE_INSTALL_DIR` if you customized it. The uninstall removes only the CLI and its previous binary, not the runtime, maps, credentials or unrelated files. Windows removes its user PATH entry only if the installer originally added it; pre-existing PATH entries and the registry value's type remain unchanged. Reinstall before uninstalling a Windows installation that predates the install receipt. The PowerShell commands run the script in memory; they do not require changing execution policy. On macOS and Linux, remove any PATH line you added yourself if you no longer need it.