> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt # Install the SurrealDB CLI Install the surreal command with the install script on macOS, Linux and Windows. Options for the database switch (--db, --no-db, SURREAL_CLI_INSTALL_DB), choosing a release, adding components, mirrors, package managers and Docker. This page installs the `surreal` command and, optionally, the components it runs. Pick one installation method; everything after it applies whichever you chose. The install script puts the `surreal` launcher on your machine, then uses it to install the database as a component and pin it, so `surreal db start` works from then on with no network connection. The script checks every download against the SHA-256 published beside it, and installs nothing if a check fails. ## Install on macOS and Linux ```bash curl -sSf https://install.surrealdb.com | sh ``` The script installs `surreal` into `/usr/local/bin`. If that folder is not writable it falls back to `~/.surrealdb`, or asks where to install when you pass `--interactive`, and then prints the `PATH` line to add. It never edits your shell profile. The script is served as plain text, so you can open the same URL in a browser and read it before you run it. Pass options after `-s --`, which is how `sh` forwards arguments to a script it reads from a pipe. ```bash curl -sSf https://install.surrealdb.com | sh -s -- --no-db --with cloud ``` ", "description": "The database release to install and pin." }, { "name": "--nightly", "short": "-n", "description": "Install the latest nightly database." }, { "name": "--beta", "short": "-b", "description": "Install the latest beta database." }, { "name": "--alpha", "short": "-a", "description": "Install the latest alpha database." }, { "name": "--with", "value": "", "description": "Further components to install, comma-separated. For example `--with cloud`." }, { "name": "--interactive", "short": "-i", "description": "Ask where to install when the default folder is not writable." }, { "name": "", "description": "Where to put `surreal`, instead of `/usr/local/bin`." }, { "name": "--help", "short": "-h", "description": "Print the options and exit." } ]} /> `--version`, `--nightly`, `--beta` and `--alpha` choose the database release, so they apply only when the database is installed. The script refuses them together with `--no-db`. ## Install on Windows Run the PowerShell script from a normal or an elevated shell. ```powershell irm https://windows.surrealdb.com | iex ``` The script installs `surreal.exe` into `C:\Program Files\SurrealDB` from an elevated shell, and into `%LOCALAPPDATA%\SurrealDB` otherwise, and adds that folder to your user `PATH`. A folder you name yourself is not added to `PATH`. `irm | iex` cannot pass options. To pass them, run the script as a script block. ```powershell & ([scriptblock]::Create((irm https://windows.surrealdb.com))) -NoDb -With cloud ``` ", "description": "The database release to install and pin." }, { "name": "-Nightly", "short": "-n", "description": "Install the latest nightly database." }, { "name": "-Beta", "short": "-b", "description": "Install the latest beta database." }, { "name": "-Alpha", "short": "-a", "description": "Install the latest alpha database." }, { "name": "-With", "value": "", "description": "Further components to install. For example `-With cloud`." }, { "name": "-Interactive", "short": "-i", "description": "Ask where to install when the install folder is not writable." }, { "name": "", "description": "Where to put `surreal.exe`." } ]} /> ## Choose whether to install the database The database is installed by default. Choose explicitly with `--db` or `--no-db` (`-Db` or `-NoDb` on Windows), or with the `SURREAL_CLI_INSTALL_DB` environment variable for callers that cannot pass options, such as `curl ... | sh` in a Dockerfile or a CI step. | Setting | Effect | | --- | --- | | `SURREAL_CLI_INSTALL_DB=1` | Install the database, as `--db` does | | `SURREAL_CLI_INSTALL_DB=0` | Install `surreal` alone, as `--no-db` does | ```bash title="Install surreal alone from a pipe" curl -sSf https://install.surrealdb.com | SURREAL_CLI_INSTALL_DB=0 sh ``` A flag wins over the variable, and the last of `--db`, `--no-db` and `--minimal` wins over the others. Because the default may change, a script that needs one outcome should say so with a flag or the variable. Without the database, `surreal db ` offers to install it the first time you run it, and `surreal install db` installs it at any time. Components installed this way follow the rules in [Managing components](/docs/explore/cli/components.md). ## Install more components `--with` installs further components in the same step, through the launcher. ```bash curl -sSf https://install.surrealdb.com | sh -s -- --with cloud ``` With `surreal` already installed, `surreal install cloud` does the same. [Managing components](/docs/explore/cli/components.md) covers versions, upgrading and pinning. ## Confirm the installation `surreal version` lists each component, the version that runs, and where it runs from. ```bash surreal version ``` ```text title="Sample output" COMPONENT VERSION SOURCE INSTALLED PATH cli 0.1.0 cli /usr/local/bin/surreal db 3.3.4 pinned 3.3.4 /home/you/.surrealdb/components/db/3.3.4/surreal-db cloud 0.1.0 pinned 0.1.0 /home/you/.surrealdb/components/cloud/0.1.0/surreal-cloud ``` `surreal --version` prints the same information on a few lines, and `surreal version --json` prints it as one JSON document. ## Where files go The launcher keeps everything it installs in one folder, the SurrealDB home. It is `~/.surrealdb` (`%USERPROFILE%\.surrealdb` on Windows) unless `SURREAL_CLI_HOME` names another folder. Each component version is a separate file under `components///`, which is what lets several versions sit side by side. ## Other ways to install ### Package managers Homebrew, Chocolatey and Scoop install the database as a single `surreal` executable, and update it through the package manager. That executable is the database itself, not the launcher: it has no `surreal db` prefix and no component management, so run its commands without `db` and update it with the package manager. See the installation pages for [macOS](/docs/running/installation/macos.md) and [Windows](/docs/running/installation/windows.md). The install script leaves a `surreal` that a package manager owns alone; remove the package first, or install into another folder. ### Docker The Docker image runs the database directly, so Docker examples use `surreal start` rather than `surreal db start`, and nothing inside the image installs or upgrades components. See [Running with Docker](/docs/running/docker.md). ### A mirror `SURREAL_CLI_DOWNLOAD_ROOT` replaces the download host, for an internal mirror. The mirror must publish the launcher under `cli/launcher/`, each component in its own folder beneath `cli/`, and the database at its root, in the same layout as `https://download.surrealdb.com`. The value is an `http` or `https` address with no user name, password, query or fragment. ### Offline machines `SURREAL_CLI_OFFLINE=1` forbids every network request. A component that is already installed runs normally, and a missing one fails at once with the command that would install it. See [Managing components](/docs/explore/cli/components.md#offline-and-unattended-use). ## Troubleshooting ### A different `surreal` runs A `surreal` earlier on your `PATH`, such as an older standalone database, runs instead of the launcher. The install script warns when it finds one. Remove the older executable, or put the launcher's folder first on `PATH`. `surreal version` shows the path each component runs from.