> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orka CLI Overview & Configuration

> Orka CLI command structure, global options, and configuration. Learn how to set your API URL, enable shell autocompletion, and navigate built-in help.

> [!NOTE]
>
> Starting with Orka 4.0, the CLI command is `orka`. Orka 3.6 is a long-term support (LTS) release, and its CLI stays `orka3`: on a 3.6 cluster, replace `orka` with `orka3` in the examples on this page. Commands marked as removed in Orka 4.0 only exist in `orka3`. You can install both CLIs side by side. If you upgrade a cluster to 4.0 and have scripts that call `orka3`, see the [Orka 4.0.0 release notes](https://docs.macstadium.com/orka/orka-upgrades-and-release-notes/orka-release-notes.md#orka-4-0-0) for a temporary `orka3` symlink while you update them.

## Getting Started with orka

**Basic Usage**

The Orka CLI follows a consistent command structure:

```
orka [command] [subcommand] [flags]
```

**Global Help**

```
orka --help
```

**Available Options**

```
-h, --help   Display help for orka
```

**Main Command Groups**

* `orka completion` - Generate autocompletion scripts for your shell
* `orka config` - Manage the local Orka CLI configuration
* `orka emulator` - Manage Android emulators. See [Manage Android emulators with the Orka CLI](https://docs.macstadium.com/orka/orka-cli-reference/emulator-management.md).
* `orka emulator-config` - (Orka 4.0 or later) Manage Android emulator configurations
* `orka image` - (Deprecated in Orka 4.0) Manage locally stored images
* `orka imagecache` - Manage individual cluster node(s) image cache
* `orka3 iso` - (Removed in Orka 4.0) Manage locally stored ISOs
* `orka login` - Log in to your Orka cluster
* `orka namespace` - (Admin-only) Manage namespaces
* `orka node` - Manage Orka nodes
* `orka rbac` - (Admin-only, Orka 4.0 or later) Manage RBAC role subjects
* `orka registrycredential` - (Admin-only) Manage OCI registry credentials
* `orka remote-image` - (Deprecated in Orka 4.0) List or pull images from the remote repository
* `orka rolebinding` - (Admin-only, deprecated in Orka 4.0) Manage rolebindings. Use `orka rbac` instead.
* `orka serviceaccount` - (Admin-only) Manage service accounts
* `orka upgrade` - Manage Orka cluster upgrades. See [Orka Upgrade Service](https://docs.macstadium.com/orka/orka-upgrades-and-release-notes/orka-upgrade-service.md).
* `orka user` - Manage your authentication with Orka
* `orka version` - Print the current version of the Orka CLI
* `orka vm` - Manage VMs
* `orka vm-config` - Manage VM configurations

## Configuration Commands

The `orka config` command group manages your local Orka CLI configuration. The first time you run the Orka CLI, you must set the Orka service URL. All Orka CLI commands are executed against this address.

**orka config set**

Set the Orka service URL for your environment.

**Syntax:**

```
orka config set --api-url ORKA_SERVICE_URL [flags]
```

**Determining Your Service URL:**

* For environments initially deployed with **Orka 2.1 or later**: typically `http://10.221.188.20`
* For environments initially deployed **before Orka 2.1**: typically `http://10.221.188.100`

If your cluster has public NAT IPs or a custom domain configured for the Orka API, use your public URL instead of the internal IP address. Using the internal IP on a cluster with public API access will result in connection timeouts.

You can also use the built-in Orka domain (COMPANY.orka.app) or an external custom domain if configured.

> [!NOTE]
>
> `orka config set --api-url` sets only the Orka API URL that the Orka CLI uses. It doesn't change the `server` entry for the cluster in your kubeconfig (`~/.kube/config`). That entry points to the Kubernetes API server, which is a separate endpoint from the Orka API. For example, the Kubernetes API server might be `10.221.188.19` on TCP 6443, while the Orka API is at `10.221.188.20`. As a result, `kubectl config view` can still show an IP address after you set `--api-url` to a hostname. For details on how the Orka CLI uses kubeconfig credentials, see [Authentication and RBAC](https://docs.macstadium.com/orka/orka-cluster-access/orka-authentication-and-rbac.md).

**Options:**

```
-a, --api-url string   (Required) The Orka service URL
-h, --help             Display help for set
```

**Examples:**

```
# Set your Orka service URL to 10.221.188.20 (Orka 2.1+)
orka config set --api-url http://10.221.188.20

# Set your Orka service URL to 10.221.188.100 (pre-Orka 2.1)
orka config set --api-url http://10.221.188.100

# Set your Orka service URL to your built-in Orka domain
orka config set --api-url https://company.orka.app

# Set your Orka service URL to an external custom domain
orka config set --api-url https://company.com
```

**orka config view**

View the current local Orka CLI configuration.

**Syntax:**

```
orka config view [flags]
```

**Options:**

```
-h, --help   Display help for view
```

**Examples:**

```
# Print your current Orka CLI configuration
orka config view
```

## Shell completion setup

The Orka CLI can generate autocompletion scripts for your shell, making it easier to discover commands and options.

**Supported Shells**

* bash
* fish
* powershell
* zsh

**Generate Completion Script**

```
orka completion [shell]
```

See each sub-command's help for details on how to use the generated script.

**Options:**

```
-h, --help   Display help for completion
```

**Bash Completion**

This script depends on the bash-completion package. If it is not installed, install it via your OS's package manager.

*Load completions in the current shell session:*

```
source <(orka completion bash)
```

*Load completions for every new session (Linux):*

```
orka completion bash > /etc/bash_completion.d/orka
```

*Load completions for every new session (macOS):*

```
orka completion bash > $(brew --prefix)/etc/bash_completion.d/orka
```

A new shell must be started for this setup to take effect.

**Options:**

```
-h, --help              Display help for bash
--no-descriptions       Disable completion descriptions
```

**Fish Completion**

*Load completions in the current shell session:*

```
orka completion fish | source
```

*Load completions for every new session:*

```
orka completion fish > ~/.config/fish/completions/orka.fish
```

A new shell must be started for this setup to take effect.

**Syntax:**

```
orka completion fish [flags]
```

**Options:**

```
-h, --help              Display help for fish
--no-descriptions       Disable completion descriptions
```

**PowerShell Completion**

*Load completions in your current shell session:*

```
orka completion powershell | Out-String | Invoke-Expression
```

To load completions for every new session, add the output of the above command to your PowerShell profile.

**Syntax:**

```
orka completion powershell [flags]
```

**Options:**

```
-h, --help              Display help for powershell
--no-descriptions       Disable completion descriptions
```

**Zsh Completion**

If shell completion is not already enabled in your environment, enable it first:

```
echo "autoload -U compinit; compinit" >> ~/.zshrc
```

*Load completions in the current shell session:*

```
source <(orka completion zsh)
```

*Load completions for every new session (Linux):*

```
orka completion zsh > "${fpath[1]}/_orka"
```

*Load completions for every new session (macOS):*

```
orka completion zsh > $(brew --prefix)/share/zsh/site-functions/_orka
```

A new shell must be started for this setup to take effect.

**Syntax:**

```
orka completion zsh [flags]
```

**Options:**

```
-h, --help              Display help for zsh
--no-descriptions       Disable completion descriptions
```

## Checking CLI Version

**orka version**

Print the current version of the Orka CLI and the versions of the Orka API server and operator on your cluster. If the Orka Upgrade Service is installed, the output also includes its operator and cluster agent versions.

**Syntax:**

```
orka version [flags]
```

**Options:**

```
--client     (Optional) Print only the version of the orka client, without contacting the cluster
-h, --help   Display help for version
```

**Examples:**

```
# Print the CLI, API server, and operator versions
orka version

# Print only the CLI version
orka version --client
```

Components on your cluster can report different version numbers, because a patch release only updates the components it changes. See [Orka component versions by release](https://docs.macstadium.com/orka/orka-upgrades-and-release-notes/orka-component-versions.md) for the expected version of each component.


## Related topics

- [Orka On-Prem architecture and networking overview](https://docs.macstadium.com/orka/orka-on-aws-and-on-prem/orka-on-prem-getting-started.md)
- [Deploy your first VM with the Orka CLI](https://docs.macstadium.com/orka/quick-start-guides/orka-cli-quick-start.md)
- [Orka macOS virtualization platform overview](https://docs.macstadium.com/orka/orka-overview/orka-overview.md)
- [Orka on AWS architecture and deployment overview](https://docs.macstadium.com/orka/orka-on-aws-and-on-prem/orka-on-aws-getting-started.md)
- [Orka tools, CLI downloads, and CI/CD plugins](https://docs.macstadium.com/orka/orka-overview/tools-integrations.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.