CLI Quick Start
How to get started with the Orka CLI. Learn how to set it up for the first time, the basic operations, and how to get help.
Time to read: 9 minutes, 19 seconds
Jump to: 1. Before you begin | 2. Download and configure the Orka CLI | 3. Create a user | 4. Some CLI basics | 5. Create and deploy your first VM instance | 6. Experience your VM instance | 7. Update the base image | 8. Time to say goodbye
The ultimate quick start
If you want to skip the detailed explanations, just run through these steps on your own:
orka user create(enable immediate login)
orka node list
orka vm list(you should see 0 results)
orka image list(you should see at least
orka vm create(use
90GBVenturaSSH.orkasiand set CPU and vCPU to 6)
orka vm listand
orka vm status
- Run Apple Screen Sharing to connect to the VM instance. Use
vnc://<VM-IP>:<Screenshare-port>with the IP and port from Step 7. Use the
- On the VM, change the login credentials, apply the latest OS updates, and install (or upgrade) the Orka VM Tools.
- If you are the sole user of the environment, run
orka image commit(use the VM instance ID as listed by
orka vm list). Otherwise, run
orka image save(use the VM instance ID as listed by
orka vm list).
orka vm deploy -v <NAME> -y(use the name of your VM config)
- Run Apple Screen Sharing and connect to the newly deployed VM. Use the connection information printed by
orka vm deploy.
orka vm delete -v <NAME> -y
orka vm list
The Orka CLI is the easiest way to get started with Orka. It provides guided, interactive completion of commands and built-in help.
The Orka CLI will be most useful to:
- beginner users
- users with predominantly manual workflows
- advanced users who need to tap into the Kubernetes layer and work with
1. Before you begin
- Get your IP Plan. You can download it from the MacStadium portal.
- Connect to your Orka cluster via VPN.
- Download and install a VPN client. Note that if you're using a custom Orka domain, you might need to make some additional configuration changes.
- Use the server address and credentials from the VPN section at the top of your IP Plan.
2. Download and configure the Orka CLI
- Download and install the latest Orka CLI that matches your environment version.
- On macOS, run the
- On Linux, unpack the archive and move the executable to
- On Windows, add the directory of the executable to your
- On macOS, run the
TIP: Using Homebrew?
brew install orka.
- Launch your preferred command-line tool (e.g., the Terminal on macOS) and run the following command:
This operation is a one-time effort. With it, you set the Orka service endpoint and your license key. The license key is required for administrative actions.
What's your Orka endpoint?
You can get the IP for your Orka endpoint from your IP Plan:
- For clusters deployed before Orka 2.1, it's the
.100address for your
- For clusters deployed with Orka 2.1 or later, it's the
.20address for your
You need to use
httpwith the IP.
Due to Node.js limitations, the Orka CLI cannot work with the built-in Orka domains and can work only with a limited number of external custom domains.
The Orka CLI works only with valid TLS certificates issued by the certificate authorities recognized by Node.js.
3. Create a user
Orka requires you to create a dedicated Orka user for your cluster. This operation also creates a dedicated namespace in the cluster. You are the owner of this namespace. When you create a VM config and/or deploy a VM instance from it, they become associated with your namespace. Other users will not be able to manage your VM configs and your VMs and vice versa. Administrators will be able to list, delete, and purge your VM configs and instances.
- In your preferred command-line tool, run the following command:
orka user create
When you log in, the Orka CLI caches your token locally and uses it to identify you uniquely with the Orka service endpoint.
Are you logged out?
If you already have a user or you get logged out from your account, you can log in with
4. Some CLI basics
The Orka CLI is a powerful tool in the hands of both inexperienced and advanced users. You can work with it one of two ways:
- Interactive mode: This is the default working mode of the Orka CLI. The CLI prompts you to fill in the missing configuration parameters for the commands that require it. It also requires explicit confirmation for some operations.
- Direct mode: For advanced users, non-interactive consoles, and scripting purposes, the Orka CLI lets you pass the configuration parameters along with the command.
If you're working mostly in interactive mode, keep in mind:
- Just start typing. Most Orka commands require strictly Latin alphanumeric input with dashes, underscores, and periods sometimes allowed (depending on the command).
- To confirm the current input, hit
arrow-downfrom the keyboard.
- To correct the current input, use
- To return to an already filled-in line and correct it, use
arrow-downfrom the keyboard.
- To navigate between prompt lines, use
- To submit a command and execute it, hit
Enterat the last prompt.
- To discard the entire command without executing it, just press
If you're working mostly in direct mode, get to know the
-y flag or the
--json flag. It lets you bypass any confirmation prompts.
The default Orka CLI output is table-formatted. To switch to
JSON format (where supported), pass the
--json flag to your Orka CLI commands. To switch to raw format (where supported), pass the
--raw flag to your Orka CLI commands. See also: CLI Commands: Change the output.
To get help, run:
5. Create and deploy your first VM instance
- Open a new command-line prompt and run:
This command shows the current status of all your nodes. Re-run this command, as you deploy VM instances later on, to keep track of the available resources on your nodes.
A genuine Apple physical host that provides computational resources (RAM and CPU) for your workloads.
A host OS runs on top and you have no direct access (via VNC, SSH, or Screen Sharing) to it.
If this is the first time you're using Orka, you will get
Not Deployed: 0.
This command lists the VM configs and VM instances associated with your user.
Do you want to see all VMs on the environment?
Run the administrative
orka vm list -f all.
Note that this operation requires a valid Orka license key to be set with
- List the available base images that you can use to create a VM config.
You will likely see a
90GBVenturaSSH.orkasi item. It is a fully installed and configured Apple Silicon-based macOS Ventura image with a 90GB disk size. It also has an admin user configured and SSH and Apple Screen Sharing access enabled.
A disk image that represents VM storage. Base images are bootable disk images that provide the OS, file system, and storage for your VM configs and VMs. Empty images provide added storage or serve as the base image during manual OS installs from ISO.
- Create your first VM config and deploy its first instance with a single command:
orka vm create
The Orka CLI prompts you to complete the configuration manually:
- VM Name: Set any user-friendly name that will help you recognize the VM.
- Base image: Set to
- CPU: Set to 6. This is the number of CPUs for the VM.
- vCPU: Set to 6. Unless CPU is 3, it must be half of or the exact amount of CPUs. This setting indicates if hyperthreading is enabled. If vCPU equals CPU, hyperthreading is on.
- Memory (G): Skip. Manually sets the memory allotted to the VM. Must not exceed the maximum available memory on the node. If not specified, Orka automatically allots the memory.
- Node Name: Skip. Manually selects the node that will host the VM. If not specified, Orka chooses automatically based on the available resources and any node dedication or node affinity settings.
- Attach ISO: Skip. Not applicable to Apple Silicon images. Use this configuration parameter to deploy a clean Intel-based VM and install its OS from ISO.
- Attach Disk: Skip. Not applicable to Apple Silicon images. Use this configuration parameter to attach additional storage to an Intel-based VM.
- GPU: Skip. Not applicable to Apple Silicon images. By default, no. This setting enables or disables GPU passthrough (when enabled on the cluster) for Intel-based VMs.
- Tag: Skip. Sets a tag for the VM and indicates that the VM should (or must) be deployed only on nodes with the specified tag (node affinity).
- Tag Required: Skip. When a tag is also specified, indicates if the VM should (
N) or must (
y) be deployed on nodes with the specified tag.
N. If left blank, defaults to
- VNC Console: Skip. By default, yes. This setting controls the VNC connectivity of the VM.
VM name limitations
The name you specify under
VM Namemust meet the following requirements:
- Doesn't exceed 38 characters.
- Contains only lowercase Latin alphanumeric characters (0-9, a-z) and dashes (-).
- Begins and ends with an alphanumeric character.
This command creates a VM config and deploys an instance from it.
Glossary: VM config
A template for an Orka virtual machine. You can deploy multiple VM instances (VMs) from a single VM config.
To list all VM configs associated with your user, run
orka vm configs.
Glossary: VM instance (VM)
A deployed instance of a VM config. VMs take up resources from your nodes and require a certain amount of CPU and memory to run.
To deploy more instances of the same config, run
orka vm deploy.
- Check your nodes and your VMs.
orka node list. Did the number of available resources change?
- List your VMs:
orka vm list
You should now see
Deployed: 1 and
Not Deployed: 0. Although it might seem so, a VM config doesn't disappear when you deploy an instance. It's just that the Orka CLI doesn't distinguish between a VM config and a VM instance. It works in terms of
orka vm list is a powerful command. It shows a lot of system information for the VM, along with the unique identifier of the instance (ID), its IP, and several connection ports. Note that even though
SSH are always listed and configured for every VM, you won't be able to use them unless the respective connection type is enabled in the macOS as well. This behavior is a security limitation of the OS.
In a pool of many VMs, are you looking for that special one?
When you have a lot of VMs, the output of
orka vm listmight become too crowded to use efficiently. Run
orka vm statusinstead and get the system information for a single VM.
orka vm statusis also the only way to get detailed information for scaled VMs.
6. Experience your VM instance
- Look at the last output of
orka vm listagain. Get that IP and
5901, respectively, in the example above.)
- Launch Apple Screen Sharing on your local machine (
Cmd+Kin Finder). Type
vnc://10.221.188.16:5901in the example above).
Are you not working on macOS?
This step works only on macOS. If you're working on a Linux or Windows machine instead, launch your preferred VNC client and connect to
10.221.188.16:5999in the example above).
For more information, see VNC, SSH, and Screen Sharing for Orka VMs.
One more thing to remember is that Screen Sharing needs to be already enabled on the macOS. Most of the time, this is not the case (especially on clean OS installs or after an ISO install), and you will need to enable the setting yourself.
The good news is that
90GBVenturaSSH.orkasi is already preconfigured for you, and you can enjoy out-of-the-box Screen Sharing and SSH connectivity.
Are you not using the 90GBVenturaSSH.orkasi image?
If you're using another image as your starting point or if you are installing your OS from ISO, you will likely not have SSH or Screen Sharing enabled by default (even though the respective ports will be mapped by default). In this case, you need to connect to the VM via VNC. You can then enable SSH and Screen Sharing connectivity in the OS.
When prompted by Apple Screen Sharing, provide the credentials for the VM (
admin/admin). You will be prompted for the password one more time - when Apple connects to the VM.
On the VM, launch System Preferences > Users & Groups. Select the Admin user and click Change password. Set the
Adminuser password to whatever works for you.
(Optional) Launch the Terminal and run the following command.
brew install orka-vm-tools OR brew upgrade orka-vm-tools
This action ensures that your VM is running the latest version of the Orka VM Tools. This collection of services lets Orka manage the guest operating system on Apple silicon-based VMs more efficiently and enables key features, such as shared VM storage.
If your cluster and CLI are not running the latest Orka version, download and install an Orka VM Tools that matches the versions of your cluster and Orka CLI.
- Apply the latest OS updates and restart the VM.
7. Update the base image
Making changes to the configuration or the file system of a running VM does not affect its base image. As soon as you delete the VM, your changes will be lost, and you will need to recreate them manually on other VMs.
To create changes that stick and appear on future deployments, you can commit your changes to the base image, or you can save the changes as a new image.
Glossary: Commit changes
Commitmodifies the original base image of the respective VM instance. With this operation, you apply the current state of a VM instance over the base image of its VM config. This way, newly deployed instances will launch in the same state as your current VM.
committo work, the base image must not be in use by any other VM instances (regardless if they were spun from the same VM config or another VM config).
This operation restarts the VM.
orka image commit --helpfor more information.
Glossary: Save changes
Savecreates a new base image from the current state of the respective VM instance. To use it, you need to create a new VM config that references the new base image.
This operation restarts the VM.
orka image save --helpfor more information.
- If you are sure that you are the only Orka user who's using
90GBVenturaSSH.orkasi, you can commit the changes. Otherwise, save a new image.
This operation will persist the new admin password and the latest OS updates. Note that you might need to share the new admin password with future users who might follow this guide.
Return to the command line on your local machine and run:
orka image commit
When prompted, provide the ID of the VM instance. (You can get it from the
orka vm list output you ran earlier.
- See how the changes are preserved for yourself. Deploy a new VM instance from your VM config:
orka vm deploy -v <NAME> -y
This syntax gives you a taste of running Orka commands in direct mode and bypassing the manual line-by-line input. Note the output of the command. The connection info for your VM shows as soon as the deployment completes.
- Launch Apple Screen Sharing and connect to the newly deployed VM instance. Use the updated admin credentials to log in.
8. Time to say goodbye
This section is optional.
When your VM configs and instances have served their purpose, you can remove them. Orka provides two ways to do that:
Glossary: Delete VM
This operation removes the specified instance(s). You can delete a VM by:
- name (deletes all VM instances with that name)
- name and node (deletes all VM instances with that name from that node)
- ID (deletes the VM instance with that ID)
Delete always preserves the original VM config, and you can deploy new VM instances from it.
orka vm delete --helpfor more information.
Glossary: Purge VM
This operation removes all VM instances and the VM config of that name. You can perform a purge even if there are no VM instances deployed.
orka vm purge --helpfor more information.
- Remove all VM instances you created until now:
orka vm delete -v <NAME> -y
- List your VMs again.
orka vm list
You should see
Deployed: 0 and
Not Deployed: 1.
You're ready to explore the Orka CLI on your own. You might find the following resources helpful:
orka helpto get a list of all the available commands.
- Explore Orka Docs for more advanced tasks and tutorials.
- Seek help from the Orka community in the MacStadium Community Slack.
- Get support in the MacStadium portal.
- Is a feature missing? Please share your feedback with us.
- If you're looking to tap into Kubernetes, see this page.
Updated 3 months ago