## Usage Guide

---

### Getting Started

---

After [installation](/doc/sdk/cli-ng/en/guides/installation) and [configuration](/doc/sdk/cli-ng/en/guides/configuration) of a profile, verify that your connection works:

```bash
rbw whoami
```

This command displays the connected Rainbow account information (name, email, roles).

### Global Options

---

These options apply to all commands:

| Option | Description |
|---|---|
| `--profile <name>` | Use the specified profile for this command |
| `--debug` | Enable detailed debug logs |
| `--verbose` | Enable verbose output |
| `--log <file>` | Write logs to a file |

Examples:

```bash
rbw --profile sandbox --debug users
rbw --log debug.log companies
```

### Main Commands

---

#### Users

```bash
rbw users                                     # List users
rbw user find <query>                         # Search by name or email
rbw user get <id>                             # User details
rbw user create <email> <pwd> <first> <last>  # Create a user
rbw user update <id>                          # Update a user
rbw user delete <id>                          # Delete a user
```

#### Companies

```bash
rbw companies                                 # List companies
rbw company find <query>                      # Search by name
rbw company get <id>                          # Company details
rbw company create <name>                     # Create a company
```

#### Applications

```bash
rbw applications                              # List applications
rbw application create <name>                 # Create an application
rbw application block <id>                    # Block an application
rbw application delete <id>                   # Delete an application
rbw application-deploy [id]                   # Deploy (interactive workflow)
```

#### API Keys

```bash
rbw apikeys                                   # List API keys
rbw apikey create <description>               # Create an API key
rbw apikey delete <id>                        # Delete an API key
```

#### Metrics

```bash
rbw metrics applications                      # Application usage metrics
rbw metrics application <id>                  # Metrics for a specific application
```

### Interactive Mode

---

List commands support an interactive mode for exploring resources in a navigable tree:

```bash
rbw users --interactive
rbw applications --interactive
rbw companies --interactive
```

**Navigation**:

| Key | Action |
|---|---|
| `↑` / `↓` | Navigate the list |
| `Enter` | Select / expand |
| `q` | Quit interactive mode |

### Data Export

---

Some commands support export and JSON output:

```bash
rbw applications -f apps.csv                  # CSV export
rbw applications --json                       # Raw JSON output
rbw companies --json                          # Raw JSON output
```

### Filters

---

List commands accept filters to narrow down results:

```bash
rbw users --company <name>                    # Filter by company
rbw users --role <role>                       # Filter by role
rbw users --email <email>                     # Filter by email
rbw applications --deployed                   # Deployed applications only
rbw applications --blocked                    # Blocked applications only
```

### Contextual Help

---

Every command has built-in help:

```bash
rbw --help                                    # General help
rbw user --help                               # Help for a command group
rbw user get --help                           # Help for a specific command
```

### Built-in REST API Documentation

---

The CLI includes a browser for the Rainbow REST API documentation:

```bash
rbw api-docs browse
rbw api-docs search <keywords>
```

An interactive TUI mode lets you browse endpoints, view their parameters, and test them directly from the terminal.

### Built-in Guides

---

Rainbow developer guides are accessible from the CLI:

```bash
rbw guides browse
rbw guides search <keywords>
rbw guides show <guide>
```
