> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-cli/installation.md).

# Installation

This guide covers everything you need to install and configure the Rumi CLI on your system.

## Platform Support

{% hint style="info" %}
The Rumi CLI officially supports macOS and Linux. Windows users can run the CLI via WSL (Windows Subsystem for Linux).
{% endhint %}

<details>

<summary>Windows users: Click here for WSL setup instructions</summary>

**Setting up WSL for Windows**

If you don't already have WSL installed, follow these steps:

1. **Install WSL**: Open PowerShell or Windows Command Prompt in administrator mode and run:

   ```powershell
   wsl --install
   ```

   This will install Ubuntu by default.
2. **Restart your computer** when prompted
3. **Launch WSL**: Open the Start menu, search for "Ubuntu" (or your chosen Linux distribution), and click to launch
4. **Complete initial setup**: Create a username and password when prompted

Once WSL is installed and running, continue with the installation instructions below (WSL provides a Linux environment, so follow the Linux instructions).

For more details, see [Microsoft's WSL installation guide](https://learn.microsoft.com/en-us/windows/wsl/install).

**Tip:** Consider using [Windows Terminal](https://aka.ms/terminal) for a better terminal experience.

</details>

## Prerequisites

Before installing the Rumi CLI, ensure your system meets the following requirements.

### Java 11+

The Rumi CLI requires Java 11 or newer to run.

**Verify Java installation:**

```bash
java -version
```

You should see version `11.x.y` or higher. If not, download and install Java from:

* [Oracle JDK Downloads](https://www.oracle.com/java/technologies/downloads/)
* [OpenJDK](https://openjdk.org/)

#### Using RUMI\_CLI\_JAVA\_HOME (Optional)

If you cannot add Java 11+ to your system PATH, you can set the `RUMI_CLI_JAVA_HOME` environment variable to point to your Java 11+ installation:

```bash
# macOS/Linux - add to ~/.bash_profile or ~/.zprofile
export RUMI_CLI_JAVA_HOME=/path/to/your/jdk11

# Verify
$RUMI_CLI_JAVA_HOME/bin/java -version
```

The Rumi CLI looks for Java in this order:

1. If `java` is in PATH and is version 11+, use it
2. Otherwise, if `RUMI_CLI_JAVA_HOME` is set and points to Java 11+, use it
3. Otherwise, exit with an error

### Docker (Required for Local Deployments)

Local deployments require Docker Desktop installed and running.

**Requirements:**

* Docker Desktop 4.0+ (or Docker Engine 20.10+ on Linux)
* Docker daemon running and accessible
* 8GB+ RAM available
* 20GB+ free disk space

**Verify Docker installation:**

```bash
docker --version
docker ps  # Should list running containers (or show empty list)
```

**Download Docker Desktop:**

* [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/)
* [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/)
* [Docker Engine for Linux](https://docs.docker.com/engine/install/)

{% hint style="warning" %}
On macOS and Windows, ensure Docker Desktop is started before running `rumi` commands for local deployments. The Docker daemon must be running.
{% endhint %}

### AWS Setup (Required for AWS Deployments)

If you plan to provision Rumi private clouds in AWS, you'll need to configure AWS access.

**Complete AWS setup guide:** See [AWS Setup](/rumi-cli/installation/aws-setup.md) for detailed instructions on installing the AWS CLI and configuring authentication using IAM credentials, IAM Identity Center (SSO), or other AWS authentication methods.

## Installing the Rumi CLI

The Rumi CLI can be installed system-wide (requires `sudo`) or user-local (no `sudo` required).

### System-wide Installation (Recommended)

System-wide installation places the CLI in `/usr/local/bin` and requires `sudo`:

```bash
curl -fsSL https://downloads.n5corp.com/rumi/cli/latest/install.sh | sudo bash
```

This makes the `rumi` command available to all users on the system.

**Install a specific version:**

```bash
curl -fsSL https://downloads.n5corp.com/rumi/cli/1.0.0/install.sh | sudo bash
```

### User-local Installation (No sudo)

If you don't have `sudo` access or prefer a user-local installation:

```bash
curl -fsSL https://downloads.n5corp.com/rumi/cli/latest/install.sh | bash -s -- --no-root
```

This installs the CLI to `$HOME/.local/bin`.

**Important:** If you see a message about `$HOME/.local/bin` not being on your PATH, add it to your shell profile:

```bash
# For bash - add to ~/.bash_profile or ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"

# For zsh - add to ~/.zprofile or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"
```

Then reload your shell configuration:

```bash
# For bash
source ~/.bash_profile

# For zsh
source ~/.zprofile
```

## Verifying Installation

After installation, verify the CLI is working:

```bash
rumi
```

**Expected output:**

```
Rumi -- The No-DB Application Platform

Rumi CLI is Rumi's command line tool. Try:

rumi help commands        list the top level commands
rumi help <command>       help on a specific command
```

## Updating the CLI

To update to the latest version, re-run the installation command:

**System-wide update:**

```bash
curl -fsSL https://downloads.n5corp.com/rumi/cli/latest/install.sh | sudo bash
```

**User-local update:**

```bash
curl -fsSL https://downloads.n5corp.com/rumi/cli/latest/install.sh | bash -s -- --no-root
```

The installer will detect the existing installation and upgrade it.

## Uninstalling the CLI

**System-wide uninstall:**

```bash
sudo rm /usr/local/bin/rumi
```

**User-local uninstall:**

```bash
rm $HOME/.local/bin/rumi
```

**Remove configuration (optional):**

```bash
rm -rf ~/.rumi
```

## Troubleshooting

### "java: command not found"

**Problem:** The CLI cannot find Java.

**Solution:**

1. Verify Java 11+ is installed: `java -version`
2. If not installed, install Java from the links above
3. If installed but not in PATH, set `RUMI_CLI_JAVA_HOME` (see above)

### "Docker daemon is not running"

**Problem:** Docker is not running (only affects local deployments).

**Solution:**

1. Start Docker Desktop (macOS/Windows)
2. Or start Docker daemon (Linux): `sudo systemctl start docker`
3. Verify: `docker ps`

### AWS Configuration Issues

**Problem:** AWS credentials not configured or invalid (only affects AWS deployments).

**Solution:** See the [AWS Setup](/rumi-cli/installation/aws-setup.md) guide for detailed AWS configuration and troubleshooting.

### "Permission denied" during installation

**Problem:** Installation script needs elevated permissions.

**Solution:**

* For system-wide install: Use `sudo` with the install command
* For user-local install: Use the `--no-root` flag and ensure `$HOME/.local/bin` is in your PATH

### CLI command shows "command not found"

**Problem:** The CLI is not in your PATH.

**Solution:**

* For system-wide install: `/usr/local/bin` should be in PATH by default
* For user-local install: Add `$HOME/.local/bin` to PATH (see above)
* Verify PATH: `echo $PATH`
* Reload shell: `source ~/.bash_profile` or `source ~/.zprofile`

## Next Steps

Now that you have the CLI installed:

* **AWS Setup (Optional)** — If you plan to deploy to AWS, see [AWS Setup](/rumi-cli/installation/aws-setup.md) to configure AWS credentials
* **Explore commands** — See [CLI Commands](/rumi-cli/commands.md) for the command reference
* **Get started** — Try the [Quickstart](/rumi-cli/commands/quickstart.md) to build your first Rumi application

## Getting Help

If you encounter issues not covered in this guide:

* Run `rumi help` for command help
* Check the [CLI Commands](/rumi-cli/commands.md) reference
* Contact Rumi support