> ## Documentation Index
> Fetch the complete documentation index at: https://mogenius-docs-self-hosted-helm-values-update.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# mogenius CLI

> Manage your mogenius clusters, resources, and workloads from the terminal with mocli

With `mocli`, you can manage your mogenius clusters, browse Kubernetes resources, stream logs, and set up port-forwarding — all from your terminal.

The CLI includes an interactive Terminal UI (TUI) that provides k9s-style navigation without requiring a local kubeconfig. Authentication is handled through the mogenius platform, giving you secure access to any connected cluster from anywhere.

## Installation

### Mac, Linux

Use [homebrew](https://brew.sh) to install `mocli`:

```bash theme={null}
brew tap mogenius/mocli
brew install mocli
```

<Note>
  On Linux with a headless machine, `mocli` requires a browser for the initial login. After the first login, your session persists locally.
</Note>

### Windows

```bash theme={null}
scoop bucket add mocli https://github.com/mogenius/homebrew-mocli
scoop install mocli
```

## Getting Started

You need a mogenius account to use `mocli`. If you don't have one yet, [sign up here](https://app.mogenius.com).

### Login

Run the following command to authenticate. Your browser will open automatically to complete the login:

```bash theme={null}
mocli login
```

Your session is stored locally, so you only need to log in once per machine.

## Terminal UI

Launch the interactive TUI to browse and manage your resources:

```bash theme={null}
mocli
```

The TUI provides a visual interface for navigating your mogenius organization, clusters, and Kubernetes resources. All keybindings are displayed at the bottom of each screen.

### Navigation

The TUI follows a hierarchical navigation pattern:

**Organization → Cluster → Namespace → Resources**

| Key        | Action                               |
| ---------- | ------------------------------------ |
| Arrow keys | Move up/down                         |
| `Enter`    | Select / drill down                  |
| `Esc`      | Go back                              |
| `q`        | Quit                                 |
| `/`        | Filter list                          |
| `:`        | Command mode (switch resource types) |

### Browsing Resources

Once you select a namespace, you'll see a list of Pods by default. Use command mode (`:`) to switch between resource types:

* `:pods` or `:po` — Pods
* `:deployments` or `:deploy` — Deployments
* `:services` or `:svc` — Services
* `:statefulsets` or `:sts` — StatefulSets
* `:daemonsets` or `:ds` — DaemonSets
* `:jobs` — Jobs
* `:cronjobs` or `:cj` — CronJobs
* `:configmaps` or `:cm` — ConfigMaps
* `:secrets` — Secrets
* `:ingresses` or `:ing` — Ingresses

The TUI also supports custom resources (CRDs) — type the resource name in command mode to browse any resource type available in your cluster.

### Viewing Logs

Select a Pod and press `Enter` to view its logs in real-time. If the Pod has multiple containers, you'll be prompted to select one.

| Key             | Action                  |
| --------------- | ----------------------- |
| `PgUp` / `PgDn` | Scroll through logs     |
| `s`             | Toggle autoscroll       |
| `w`             | Toggle word wrap        |
| `Esc`           | Return to resource list |

### Port Forwarding

From the logs view or resource list, press `t` to create a port-forward tunnel to the selected Pod. Enter the port mapping (e.g., `8080:80`) and the tunnel will be established.

Active tunnels persist while the TUI is running. Press `Esc` from the port-forward view to return to browsing while keeping tunnels open.

### Shell Access

Select a Pod and press `x` to open an interactive shell session in the container. If the Pod has multiple containers, you'll be prompted to select one.

The shell session is tunnelled through the mogenius platform — no local kubeconfig or direct cluster access required.

## CLI Commands

In addition to the TUI, `mocli` provides kubectl-style CLI commands for scripting and automation.

### Context Management

Before using resource commands, set up your context to specify which organization, cluster, and namespace to target:

```bash theme={null}
# Interactive setup — select org, cluster, and default namespace
mocli config use-context

# Non-interactive setup
mocli config use-context --org acme --cluster prod -n acme-staging

# Show current context
mocli config current-context

# List available organizations and clusters
mocli config list
```

The context is stored locally and used by all resource commands. You can override it per-command with `--org`, `--cluster`, or `-n` flags.

### Listing and Getting Resources

```bash theme={null}
# List all pods in a namespace
mocli get pods -n acme-staging

# Get a specific resource
mocli get deployment my-app -n acme-staging

# Output as YAML or JSON
mocli get configmap my-config -n acme-staging -o yaml
mocli get secret db-credentials -n acme-staging -o json

# Wide output with additional columns
mocli get pods -n acme-staging -o wide

# List cluster-scoped resources
mocli get crd
mocli get namespaces
```

`mocli list` is an alias for `mocli get` when listing all resources of a kind:

```bash theme={null}
mocli list pods -n acme-staging
mocli list cronjobs -n acme-staging
```

### Creating Resources

Create resources from manifest files or directly via CLI:

```bash theme={null}
# Create from a YAML manifest (supports multi-document files)
mocli create -f manifest.yaml -n acme-staging

# Create a namespace
mocli create namespace acme-staging

# Create a Job with a container image
mocli create job db-migration --image=postgres:15 -n acme-staging

# Create a Job with a custom command
mocli create job db-migration --image=postgres:15 -n acme-staging -- pg_dump -h db

# Create a Job from a CronJob template (trigger a one-off run)
mocli create job --from=cronjob/nightly-backup -n acme-staging
```

### Deleting Resources

```bash theme={null}
# Delete a specific resource (prompts for confirmation)
mocli delete pod my-pod-abc123 -n acme-staging
mocli delete job db-migration -n acme-staging

# Skip confirmation prompt
mocli delete pod my-pod-abc123 -n acme-staging -y

# Delete resources defined in a manifest
mocli delete -f manifest.yaml
```

### Shell Access

Open an interactive shell in a running container:

```bash theme={null}
# Shell into a pod (uses first container if multiple)
mocli shell my-pod -n acme-staging

# Specify a container
mocli shell my-pod -c app -n acme-staging
```

`mocli exec` is an alias for `mocli shell`.

### Viewing Logs (CLI)

Stream or fetch logs from pods and jobs:

```bash theme={null}
# View logs from a pod
mocli logs my-pod -n acme-staging

# View logs from a specific container (multi-container pods)
mocli logs my-pod -c app -n acme-staging

# Stream logs in real-time
mocli logs my-pod -f -n acme-staging

# View logs from a Job (automatically finds the pod)
mocli logs job/db-migration -n acme-staging
```

### Waiting for Conditions

Wait for a resource to reach a specific condition — useful in CI/CD pipelines:

```bash theme={null}
# Wait for a Job to complete
mocli wait job/db-migration --for=condition=complete -n acme-staging

# Wait for a Job to complete with timeout
mocli wait job/db-migration --for=condition=complete --timeout=10m -n acme-staging

# Wait for a Pod to be ready
mocli wait pod/my-pod --for=condition=ready -n acme-staging

# Wait for a resource to be deleted
mocli wait pod/my-pod --for=delete -n acme-staging
```

**Supported conditions:**

* `condition=complete` — Job completed successfully
* `condition=failed` — Job failed
* `condition=ready` — Pod is ready
* `delete` — Resource has been deleted

### Authentication

```bash theme={null}
# Browser-based login (interactive)
mocli login

# API key login (for CI/CD pipelines)
mocli login --api-key <api-key>

# Or use environment variable
export MOGENIUS_API_KEY=<api-key>
mocli login --api-key

# Logout
mocli logout
```

<Tip>
  **CI/CD Integration:** For automated pipelines, create an API key in your mogenius profile settings. The API key is a single opaque token starting with `mo_pat:`. Set the `MOGENIUS_API_KEY` environment variable and `mocli` automatically uses API key authentication.
</Tip>

### Cluster Management

```bash theme={null}
# Install the mogenius operator on a cluster
mocli cluster connect

# Version info
mocli version
```

## Connecting a Cluster

You can use the CLI to install the mogenius operator on your Kubernetes cluster:

1. Run the connect command:
   ```bash theme={null}
   mocli cluster connect
   ```
2. Select an organization
3. Create a new cluster entry or select an existing one
4. Confirm to deploy the operator

The operator will be deployed to your cluster via Helm. Verify the connection through the mogenius UI or by running `mocli config list` to see your available clusters.

## Port Forwarding (CLI)

Use the CLI to create secure TCP tunnels to Kubernetes workloads without direct cluster access:

```bash theme={null}
mocli port-forward -n <namespace> -k <kind> -w <workload-name> -p <local>:<remote>
```

Supported resource kinds: `Pod`, `Service`, `Deployment`, `StatefulSet`, `DaemonSet`

**Examples:**

```bash theme={null}
# Forward to a Service
mocli port-forward -n production -k Service -w postgres -p 5432:5432

# Forward to a Deployment
mocli port-forward -n staging -k Deployment -w api-server -p 8080:8080

# Forward to a specific Pod
mocli port-forward -n default -k Pod -w my-pod-abc123 -p 3000:3000
```

| Flag              | Description                            |
| ----------------- | -------------------------------------- |
| `-n, --namespace` | Kubernetes namespace (required)        |
| `-k, --kind`      | Resource kind (required)               |
| `-w, --name`      | Workload name (required)               |
| `-p, --port`      | Port mapping `LOCAL:REMOTE` (required) |

The tunnel remains active while the CLI process runs. Press `Ctrl+C` to terminate.

For detailed usage and options, see [Tunnels](/workspaces/tunnels).