> 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/what-is-the-cli.md).

# What is the CLI

The Rumi CLI is a command-line interface tool that provides a unified interface for managing Rumi applications and infrastructure. It consolidates various operational and development tools into a single, easy-to-use command-line utility.

## Overview

The Rumi CLI (`rumi`) is the primary tool for:

* **Deploying Private Clouds**: Provision and deploy Rumi private cloud environments across different platforms (local, AWS, Hetzner, Civo, bare metal)
* **Operating Applications**: Administer, monitor and troubleshoot running microservices
* **Quickstart Support**: Create quickstart applications for tutorials and learning
* **Application Development**: Perform development activities on your Rumi applications - add/remove services, messages, handlers, and more

## Key Features

### Unified Tooling

The CLI consolidates multiple tools that were previously separate in X Platform (examples):

* **Transaction Log Tool** → `rumi tools tlt` - Query and analyze transaction logs
* **Stats Dump Tool** → `rumi tools hbdump` - Dump container heartbeats and statistics
* **Admin Tool** → `rumi tools admin` - Administrative operations on running microservices
* **Discovery Tool** → `rumi tools discovery` - Service discovery operations
* And more...

### Cloud Management

Deploy and manage Rumi private clouds across multiple platforms (examples):

* **Local Development** → `rumi cloud local` - Run Rumi on your development machine
* **AWS Deployment** → `rumi cloud aws` - Deploy to Amazon Web Services
* **Hetzner Deployment** → `rumi cloud hetzner` - Deploy to Hetzner Cloud
* **Civo Deployment** → `rumi cloud civo` - Deploy to Civo cloud ⚠️ *HTTPS in preview*
* **Bare Metal** → Configure and deploy to physical infrastructure
* And more...

### Quickstart

Bootstrap quickstart applications for tutorials:

```bash
rumi quickstart
```

Creates quickstart application projects with:

* Sample microservice code
* ADM message and state models
* Configuration templates
* Build and deployment scripts

### Application Development

> **⚠️ In Development**: The `rumi dev` command is currently in development and is subject to change.

Perform development activities on your Rumi applications. Example commands include:

```bash
# Add a new service
rumi dev service add <service-name>

# Add a new message
rumi dev message add <message-name>

# Add a message handler
rumi dev handler add <handler-name>

# Remove components as needed
rumi dev service remove <service-name>
```

Incrementally evolve your applications by managing:

* Microservices
* Messages and state entities
* Message handlers
* Configuration
* And more...

See the [dev command reference](/rumi-cli/commands/dev.md) for the complete set of development commands.

## Command Structure

The CLI follows a hierarchical command structure:

```
rumi [global-flags] <command> <subcommand> [options]
```

**Example commands**:

```bash
# Deploy to local cloud
rumi cloud local start

# Query transaction logs
rumi tools tlt /path/to/app.log

# Dump container heartbeats
rumi tools hbdump -l /path/to/heartbeats.log

# Dump transaction stats (with 3.x compatibility)
rumi --3x tools txnstats dump -l /path/to/app.txnstats.log
```

## Global Flags

The following flags can be used with any `rumi` command:

| Flag                  | Description                                                                                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--help`, `-h`        | Display help for any command. Works at every level: `rumi --help`, `rumi cloud --help`, `rumi cloud aws provision --help`, etc.                      |
| `--3x`                | Enable X Platform 3.x compatibility mode. Required when working with X Platform 3.x logs, containers (XVMs), or any 3.x artifacts or components.     |
| `--extra-jars <jars>` | Comma-separated list of additional JAR files to add to the classpath. Useful for loading application-specific message factories when analyzing logs. |

**Examples**:

```bash
# Process a log file from an X Platform 3.x application
rumi --3x tools tlt /path/to/3x-app.log

# Load application JARs for log analysis
rumi --extra-jars /path/to/app.jar,/path/to/models.jar tools tlt /path/to/app.log

# Combine flags
rumi --3x --extra-jars /path/to/app.jar tools txnstats dump -l /path/to/app.txnstats.log
```

## Environment Variables

| Variable             | Description                                                                         |
| -------------------- | ----------------------------------------------------------------------------------- |
| `RUMI_CLI_JAVA_HOME` | Path to a Java 11+ installation. Used if `java` on PATH is missing or too old.      |
| `JAVA_OPTS`          | Additional JVM options to pass to the CLI. Cannot override required internal flags. |

**Examples**:

```bash
# Specify Java installation
export RUMI_CLI_JAVA_HOME=/usr/lib/jvm/java-11-openjdk

# Increase heap size
export JAVA_OPTS="-Xmx4g"
rumi tools tlt /path/to/large.log
```

## Installation

The Rumi CLI is available for macOS and Linux (Windows via WSL):

**System-wide installation (recommended):**

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

**User-local installation (no sudo):**

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

**Verify installation:**

```bash
rumi
```

See [Installation](/rumi-cli/installation.md) for detailed installation instructions, prerequisites, and troubleshooting.

## Getting Started

1. **Install the CLI**: Follow the [Installation](/rumi-cli/installation.md) guide
2. **Run Quickstart**: Create your first application with `rumi quickstart`
3. **Deploy Locally**: Test your application with `rumi cloud local start`
4. **Explore Commands**: Browse the [Commands](/rumi-cli/commands.md) reference

## Comparison with X Platform Tools

| X Platform Tool   | Rumi CLI Command       | Purpose                         |
| ----------------- | ---------------------- | ------------------------------- |
| `xtxnlogtool`     | `rumi tools tlt`       | Transaction log queries         |
| `xstats`          | `rumi tools hbdump`    | Heartbeat and stats dumps       |
| Admin Tool        | `rumi tools admin`     | Administrative operations       |
| Discovery Tool    | `rumi tools discovery` | Service discovery               |
| (Various scripts) | `rumi cloud`           | Cloud deployment and management |

## Next Steps

* [Installation](/rumi-cli/installation.md) - Install the Rumi CLI
* [Commands Reference](/rumi-cli/commands.md) - Browse all available commands
* [Quickstart](/rumi-cli/commands/quickstart.md) - Create your first application
* [Cloud Commands](/rumi-cli/commands/cloud.md) - Deploy to different environments