> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the CLI

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

`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](/sign-in.md).

Linux and macOS:

```sh theme={null}
curl -fsSL https://simforge.ai/install.sh | sh
```

Windows (PowerShell):

```powershell theme={null}
irm https://simforge.ai/install.ps1 | iex
```

Use these terminal installation commands. New macOS releases use Developer ID signing and notarization; older Mac releases and Windows binaries may still be unsigned. macOS checks a bare executable's notarization ticket online, so its first launch needs internet access. 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](/sign-in.md), 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).

On Windows, keep the default short `%LOCALAPPDATA%\SimForge\bin` prefix for shell use. The installer can write longer paths, but PowerShell 5.1 and some .NET launchers can reject executable paths over 260 characters even when installation succeeded; choose a shorter `SIMFORGE_INSTALL_DIR` rather than changing system policy.

## Check the install

```sh theme={null}
simforge --version
```

Then [sign in](/sign-in.md). 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](/cloud.md).
* **On this machine.** [Install the runtime](/sign-in.md#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 theme={null}
simforge doctor
```

`simforge doctor` runs right after the install, with or without the runtime. It checks the sign-in, the runtime (and every place it looked when there is none), free disk for the runtime and the maps, whether the GPU supports local 3D and is free right now, ffmpeg, the map cache and the host's map catalogue; with the runtime installed it adds the runtime's own checks (the GPU adapter it would render on, sky plates, the open-file limit, the actor models). Each check reports `ok`, `warn`, `fail` or `skipped`, and every `warn` or `fail` comes with its fix. A machine without a runtime or a GPU gets warnings, not failures: `--cloud` needs neither, and simulation and 2D renders run on the CPU. `--offline` makes no network request; the checks that need one are reported as skipped, never as ok. A failing check you cannot fix? `simforge feedback --include-doctor "<what you were doing>"` sends us the checks ([what it sends](/feedback.md)).

## 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. For authoring, simulation and 2D renders: the 2D runtime (about 140 MB installed) and each map's 2D install (tens of MB); `--cloud` needs neither. A local 3D render needs the 3D runtime (about 4.3 GB to download, 5.2 GB installed) and the map with its 3D environment (about 5 to 22 GB to download). `simforge runtime status --available` and `simforge maps show <map>` give the exact sizes; an install needs its download and its unpacked size free at once, and is refused before downloading when they do not fit (`disk_insufficient`).
* A shared or busy GPU: `SIMFORGE_GPU=none` keeps local work off it. 3D and schematic renders are then refused (`gpu_disabled`; render them with `--cloud`), and 2D renders and simulation run on the CPU as always.

## 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 theme={null}
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 theme={null}
curl -fsSL https://simforge.ai/install.sh | sh -s -- --uninstall
```

Windows (PowerShell):

```powershell theme={null}
& ([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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.