> 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rumi.systems/rumi-cli/installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.