> ## 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 cluster upgrades with the CLI > Orka CLI reference for orka upgrade: start a cluster upgrade, check its progress and history, and inspect Upgrade Service and its per-node agents. > [!NOTE] > > Starting with Orka 4.0, the CLI command is `orka`. On Orka 3.6, it's `orka3`: replace `orka` with `orka3` in the examples on this page. ## Understanding cluster upgrades The `orka upgrade` commands drive Orka Upgrade Service. An upgrade is a run that moves Upgrade Service and its agents, then Mac node components, then the control plane and remaining Orka services to a target release, in that order. Only one run is active at a time. Upgrade Service keeps the 10 most recent completed runs, including failed ones, and you retry a failed upgrade by starting a new run. For when to use Upgrade Service, how to install it on your deployment, and how to troubleshoot a run, see [Orka Upgrade Service](https://docs.macstadium.com/orka/orka-upgrades-and-release-notes/orka-upgrade-service.md). ## Starting an upgrade ### orka upgrade run Start an upgrade by creating a run for the target release. Run names are timestamped, so a retry never collides with an earlier run. **Admin only:** Starting an upgrade requires administrative privileges. > [!NOTE] > > Upgrade Service doesn't perform the upgrade from Orka 3.6 to 4.0. To upgrade to 4.0, contact [MacStadium support](mailto:support@macstadium.com) to schedule it. **Syntax:** ```bash theme={null} orka upgrade run --version VERSION [flags] ``` **Options:** ``` -h, --help Display help for run -o, --output string (Optional) Output format: table (default)|json --version string Target Orka release, for example 3.6.4 (or 'latest') ``` **Examples:** ```bash theme={null} # Upgrade the cluster to a specific release orka upgrade run --version 3.6.4 # Upgrade to the highest available release orka upgrade run --version latest ``` `latest` resolves to the highest release marked available in the MacStadium release index, which can be a newer release line than your cluster's. To stay on a specific release, pass its exact version. ## Checking upgrades ### orka upgrade versions Show the cluster's current Orka release and any active upgrade run. Until a cluster completes its first successful run, the current version shows as `unknown`. **Syntax:** ```bash theme={null} orka upgrade versions [flags] ``` **Options:** ``` -h, --help Display help for versions -o, --output string (Optional) Output format: table (default)|wide|json ``` **Examples:** ```bash theme={null} orka upgrade versions ``` ### orka upgrade status Show the step list and per-node counts of the latest upgrade run, or of the run you name. **Syntax:** ```bash theme={null} orka upgrade status [RUN] [flags] ``` **Options:** ``` -h, --help Display help for status -o, --output string (Optional) Output format: table (default)|wide|json ``` **Examples:** ```bash theme={null} # Show the latest run's progress orka upgrade status # Show a specific run orka upgrade status upgrade-3-6-4-20261102-140501 # Show a run's per-node detail, including skip reasons orka upgrade status upgrade-3-6-4-20261102-140501 --output json ``` ### orka upgrade history List retained upgrade runs, newest first, with each run's target, source version, phase, duration, and age. Upgrade Service keeps the 10 most recent completed runs, so export any older ones you need for your records. **Syntax:** ```bash theme={null} orka upgrade history [flags] ``` **Options:** ``` -h, --help Display help for history -o, --output string (Optional) Output format: table (default)|wide|json ``` **Examples:** ```bash theme={null} orka upgrade history ``` ## Inspecting Upgrade Service The `orka upgrade service` commands always default to the `orka-default` namespace. They ignore the `ORKA_DEFAULT_NAMESPACE` environment variable and the kubeconfig context. See [Namespace management](https://docs.macstadium.com/orka/orka-cli-reference/namespace-management.md). ### orka upgrade service status Show Upgrade Service's operator version and status. **Syntax:** ```bash theme={null} orka upgrade service status [--namespace TARGET_NAMESPACE] [flags] ``` **Options:** ``` -h, --help Display help for status -o, --output string (Optional) Output format: table (default)|json -n, --namespace string (Optional) Namespace of the OrkaNodes to inspect (default "orka-default") ``` **Examples:** ```bash theme={null} orka upgrade service status ``` ### orka upgrade service agents List the per-node upgrade agents with each agent's installed version, status, and lease age. Unhealthy agents (`MISSING` or `STALE`) are listed first. **Syntax:** ```bash theme={null} orka upgrade service agents [--namespace TARGET_NAMESPACE] [flags] ``` **Options:** ``` -h, --help Display help for agents -o, --output string (Optional) Output format: table (default)|wide|json -n, --namespace string (Optional) Namespace of the OrkaNodes to inspect (default "orka-default") ``` **Examples:** ```bash theme={null} # List the agents orka upgrade service agents # List the agents in JSON, for a support request orka upgrade service agents --output json ``` ## Related topics - [Run guided Orka cluster upgrades with Upgrade Service](https://docs.macstadium.com/orka/orka-upgrades-and-release-notes/orka-upgrade-service.md) - [How to upgrade your Orka cluster](https://docs.macstadium.com/orka/orka-upgrades-and-release-notes/orka-upgrades.md) - [Upgrade a self-managed Orka Anywhere cluster](https://docs.macstadium.com/orka/orka-upgrades-and-release-notes/upgrading-orka-anywhere.md) - [Orka CLI command quick reference](https://docs.macstadium.com/orka/orka-cli-reference/command-quick-reference.md) - [Orka CLI Overview & Configuration](https://docs.macstadium.com/orka/orka-cli-reference/orka-cli-overview-configuration.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.