Android tests on a separate stack? Orka 4.0 runs them beside your iOS builds.
READ THE BLOG

Your AI agent now knows Orka

Rin Oliver
|
November 4, 2026

A deeper look at what the Orka CLI Agent Skill actually does, how execution and guidance modes differ, and what you can ask your agent to do.

If you work with Orka daily, you know the CLI is powerful. You also know that "powerful" often means a lot of flags and subcommands. Even experienced users end up tabbing out to the docs mid-pipeline to double-check an async flag or confirm the right syntax for a VM configuration template.

Load it into your AI coding agent once, and it knows how Orka works. Not in a general, "I have read the internet" way, but with structured, accurate knowledge of command syntax, workflow patterns, troubleshooting procedures, and architecture-specific behavior. You describe what you need, it generates or runs the right Orka command.

The Orka CLI skill

The skill repository covers the full Orka operational surface across four areas:

  • orka-cli/SKILL.md: Core concepts, command quick reference, v4.0 features, and log sources
  • orka-cli/references/commands/: Full command syntax organized by domain (VM, image, node, admin, config, registry, vm-config, emulators, upgrades, and the REST API)
  • orka-cli/references/workflows/: Step-by-step guides for CI/CD setup, scaling, migration, image prep, admin setup, and shared disk configuration
  • orka-cli/references/troubleshooting/: Auth, deployment, image, and network issue resolution
    ‍
  • orka-cli/references/references/integrations/: GitHub Actions, GitLab, Jenkins, Buildkite, TeamCity, Packer

Generic LLMs regularly get niche CLIs wrong, handing you plausible-sounding commands with (sometimes subtle) errors. This skill is structured specifically around Orka, so the commands your agent generates are actually correct.

Execution vs. Guidance: Understanding the two modes

Not all agents work the same way when it comes to actually running commands and this skill has slightly different capabilities depending on which agent you are using.

Execution-capable agents - Claude Code, Gemini CLI, and GitHub Copilot - will run orka commands directly on your machine. You describe what you want, the agent plans the steps, and with your confirmation it executes them. This is the highest-leverage mode: you can deploy VMs, query cluster state, and troubleshoot live issues without leaving your terminal.

Guidance-only agents (Cursor, Windsurf, Claude Desktop, ChatGPT) use the same underlying skill content but give you the correct commands to run yourself rather than executing them. This is still genuinely useful. Getting accurate orka syntax and a step-by-step workflow from Cursor while you are already in your editor is faster than switching to a browser and navigating docs.

One important note for execution mode: your machine needs network access to your Orka cluster (a VPN for MacStadium-hosted clusters) plus an authenticated orka session to your Orka cluster before invoking CLI commands. And as with any agent running infrastructure commands, review what it plans to do before confirming, especially anything touching production namespaces.

What you can ask the Orka skill to do

With the skill loaded, you can ask your agent about anything in the Orka operational surface. A few of the more useful scenarios:

VM management in plain English. "Deploy three VMs with macOS Sonoma, 8 CPUs, tagged for the iOS build pool" translates directly into the right orka vm deploy invocations with the correct flags. The skill also covers disk resize, pushing a VM to an OCI image, and the distinctions between local and OCI image sources.

CI/CD pipeline and service account setup. One of the more tedious parts of standing up a new Orka-backed CI/CD pipeline is the service account and token configuration. The skill includes full workflow coverage for this: creating service accounts, generating auth tokens, and wiring up the pipeline config. You can walk through the entire setup conversationally rather than hunting through the docs for the right sequence of commands.

Live troubleshooting mid-pipeline. This is where execution mode earns its keep. SSH failures, stuck image pulls, idle VMs that should have been cleaned up: instead of manually running a series of diagnostic commands, you describe the symptom and let the agent query the cluster directly. The troubleshooting reference covers auth, deployment, image, and network issues, giving the agent a structured playbook to work from.

Orka 3.6 and 4.0 guidance. Orka 4.0 exclusively supports Apple silicon and it removed Intel features like GPU passthrough, ISO attach, and power operations. The skill knows what changed between 3.6 and 4.0, gives you orka commands for 4.0 clusters, and still covers Intel on 3.6 clusters through orka3, so you get answers that match the cluster you're actually running.

Pair it with the MacStadium Docs MCP

The CLI Agent Skill and the MacStadium Docs MCP server are designed to complement each other. The skill handles operational tasks: run this command, set up this workflow, diagnose this issue. The Docs MCP handles knowledge questions: what does this feature do, how is this configured, what are the options for this resource type.

To add the Docs MCP to Claude Code alongside the skill:

claude mcp add --transport http macstadium-docs https://docs.macstadium.com/mcp

With both loaded, your agent can handle "do this in Orka" and "what does this Orka feature do" without leaving the terminal.

Getting started

*If you have an earlier version of the skill installed delete ~/.claude/skills/orka3-cli first.

‍

Installation for Claude Code is a single unzip:

Download the latest release from: github.com/macstadium/orka-cli-agent-skill/releases

unzip orka-cli-v*.skill -d ~/.claude/skills/orka-cli

Claude Code auto-discovers skills from ~/.claude/skills/. Restart Claude Code, run /orka-cli to verify, and you are set.

‍

For Gemini CLI, copy SKILL.md into your Gemini context file:

cat orka-cli/SKILL.md >> ~/.gemini/GEMINI.md

‍

Add the skill content to your repository's Copilot instructions file:

cat orka-cli/SKILL.md >> .github/copilot-instructions.md

For personal use across all repos, go to Settings > Copilot > Custom Instructions in GitHub and paste the contents of SKILL.md.

‍

Installation instructions for additional supported agents are in the support docs.

‍

Ready to try it? Get the skill at github.com/macstadium/orka-cli-agent-skill. Questions? Contact our team.

‍

Editor's Note: 
This blog was originally published in June 2026 and has been updated to reflect changes in the newest version of Orka and the CLI skill.