> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mogenius.com/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.

## Self-Hosted Instances

By default, `mocli` connects to the mogenius cloud at `app.mogenius.com`. If you run a self-hosted mogenius platform, point `mocli` at your own instance by editing its configuration file.

The config file lives at:

| OS         | Path                               |
| ---------- | ---------------------------------- |
| Mac, Linux | `~/.mocli/config.yaml`             |
| Windows    | `%USERPROFILE%\.mocli\config.yaml` |

Replace the endpoints in the `services` block with the URLs of your self-hosted deployment:

```yaml theme={null}
services:
  api:      "https://platform-api.mogenius.example.com/"
  user:     "https://platform-user.mogenius.example.com/"
  platform: "https://app.mogenius.example.com/"
  ws:       "wss://k8s-cmd-stream.mogenius.example.com"
  socket:   "https://platform-ws.mogenius.example.com"
```

All five endpoints refer to the same self-hosted instance. Ask your platform administrator for the exact hostnames if you are unsure — they follow the DNS scheme configured during installation.

<Note>
  `mocli` must be able to reach these endpoints over the network from the machine it runs on. In restricted environments where the platform is only reachable from inside a managed desktop or jump host (for example via a VDI or bastion), run `mocli` there rather than on your local machine.
</Note>

After updating the endpoints, log in against your instance. In locked-down environments where the browser callback used by `mocli login` is blocked, use API key authentication instead — it needs no local callback server:

```bash theme={null}
mocli login --api-key mo_pat:<your-api-key>
```

Create the API key in your mogenius profile settings on the self-hosted instance. See [Authentication](#authentication) for details.

## 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
```

### Applying Resources

Apply a manifest with create-or-update semantics — resources that don't exist yet are created, and resources that already exist are updated in place. Applying the same manifest twice is safe (idempotent):

```bash theme={null}
# Apply a manifest (creates or updates resources)
mocli apply -f deployment.yaml -n acme-staging

# Apply a multi-document manifest
mocli apply -f manifests.yaml -n acme-staging
```

Unlike `mocli create`, which fails when a resource already exists, `mocli apply` reconciles the cluster to match your manifest — making it the safer choice for repeatable deployments and CI/CD pipelines.

### 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
```

### Shell Autocompletion

`mocli` can complete commands, flags, and even live resource names, namespaces, and kinds directly in your shell.

The quickest way is to let `mocli` detect your shell and set everything up automatically:

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

This adds a source line to your shell's config file (`~/.zshrc`, `~/.bashrc`) or writes a completion file for fish (`~/.config/fish/completions/`). The command is idempotent — running it twice does nothing. Restart your shell or re-source the config file to activate it.

To set it up manually, generate the completion script for your shell:

```bash theme={null}
mocli completion zsh
mocli completion bash
mocli completion fish
mocli completion powershell
```

<Tip>
  Autocompletion is dynamic: when you tab-complete a resource name, namespace, or kind, `mocli` queries your active context live — so you get the real names from your cluster, not just static command names.
</Tip>

## 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).