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.

🚧

Quick navigation

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:

  1. orka config
  2. orka user create (enable immediate login)
  3. orka node list
  4. orka vm list (you should see 0 results)
  5. orka image list (you should see at least 90GCatalinaSSH.img)
  6. orka vm create (use 90GCatalinaSSH.img and set CPU and vCPU to 6)
  7. orka vm list and orka vm status
  8. 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 admin/admin credentials.
  9. On the VM, change the login credentials and apply the latest OS updates.
  10. 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).
  11. orka vm deploy -v <NAME> -y (use the name of your VM config)
  12. Run Apple Screen Sharing and connect to the newly deployed VM. Use the connection information printed by orka vm deploy.
  13. orka vm delete -v <NAME> -y
  14. 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:

1. Before you begin

  1. Get your IP Plan. You can download it from the MacStadium portal.
  2. Connect to your Orka cluster via VPN.
    1. 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.
    2. Use the server address and credentials from the VPN section at the top of your IP Plan.

2. Download and configure the Orka CLI

📘

IMPORTANT

Currently, the Orka CLI is distributed as an unsigned package. On macOS, you will be prompted that the app cannot be opened because it's from an unidentified developer. This behavior is expected.

Follow Apple's instructions to add the Orka CLI as a security exception.

  1. Download and install the latest Orka CLI.
    • On macOS or Linux, unpack the archive and move the executable to /usr/local/bin. On macOS, right-click the executable and select Open. Confirm that you want to run the software.
    • On Windows, add the directory of the executable to your PATH.
  2. Launch your preferred command-line tool (e.g., the Terminal on macOS) and run the following command:
orka config

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. It's the .100 address for your Private-1 network (usually, 10.221.188.100 or 10.10.10.100). You need to use http with the IP.

To get the custom domain for your Orka cluster, if enabled:

  1. Log into your MacStadium account.
  2. Go to Subscriptions (from the top right corner) and select your Orka cluster.
  3. In the Subscription & Plan details, find your custom domain at the bottom. If you don't see a custom domain field, it's not enabled for your environment yet.
    You need to use https with your custom domain.

Note that you can use http://<orka-IP> and https://<orka-custom-domain> (if enabled) interchangeably in your workflows.

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 orka login.

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 correct the current input, use Delete or Backspace.
  • When you're ready with a command parameter, press Enter to move to the next prompt (or execute the command, if this was the last prompt).
  • You can't cycle back to an input that you already confirmed with Enter. You can't correct past input.
  • If you made a mistake and want to exit the entire command, just press Ctrl+C. You can call the command again and re-enter your input.

If you're working mostly in direct mode, get to know the -y 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. See also: CLI Commands: Change the output.

To get help, run:

orka help

5. Create and deploy your first VM instance

  1. Open a new command-line prompt and run:
orka node list

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.

📘

Glossary: Node

A genuine Apple physical host that provides computational resources (RAM and CPU) for your workloads.

  1. Run:
orka vm list

If this is the first time you're using Orka, you will get Deployed: 0, Not Deployed: 0.

This command lists the VM configs and VM instances associated with your user. You will never see the VMs of other users.

👍

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 orka config.

  1. List the available base images that you can use to create a VM config.
orka image list

You will likely see a 90GCatalinaSSH.img item. It is a fully installed and configured macOS Catalina image with a 90G disk size. It also has an admin user configured and SSH and Apple Screen Sharing access enabled.

📘

Glossary: Image

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.

  1. 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 90GCatalinaSSH.img.
  • 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.
  • Deploy Node: Skip. Manually selects the node that will host the VM. If not specified, Orka chooses automatically based on the available resources.
  • ISO: Skip. Use this configuration parameter to deploy a clean VM and install its OS from ISO.
  • Attach Disk: Skip. Use this configuration parameter to attach additional storage to the VM.
  • VNC Console Enable: Skip. By default, yes. This setting controls the VNC connectivity of the VM.

📘

VM name limitations

The name you specify under VM Name must 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.

  1. Check your nodes and your VMs.
    • Re-run 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 Deployed and Not Deployed.

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 Screenshare and 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 list might become too crowded to use efficiently. Run orka vm status instead and get the system information for a single VM.

Note that orka vm status is also the only way to get detailed information for scaled VMs.

6. Experience your VM instance

  1. Look at the last output of orka vm list again. Get that IP and Screenshare port. (10.10.10.4 and 5903, respectively, in the example above.)
  2. Launch Apple Screen Sharing on your local machine. In Connect To:, type vnc://<VM-IP>:<Screenshare-port> (vnc://10.10.10.4:5903 in 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 <VM-IP>:<VNC-port> (10.10.10.4:6002 in 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 90GCatalinaSSH.img is already preconfigured for you, and you can enjoy out-of-the-box Screen Sharing and SSH connectivity.

📘

Are you not using the 90GCatalinaSSH.img 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.

  1. 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.

  2. On the VM, launch System Preferences > Users & Groups. Select the Admin user and click Change password. Set the Admin user password to whatever works for you.

  3. 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

Commit modifies 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.

For commit to 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.

Run orka image commit --help for more information.

📘

Glossary: Save changes

Save creates 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.

Run orka image save --help for more information.

  1. If you are sure that you are the only Orka user who's using 90GCatalinaSSH.img, 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.

  1. 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.

  1. 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: delete and purge.

📘

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.

Run orka vm delete --help for 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.

Run orka vm purge --help for more information.

  1. Remove all VM instances you created until now:
orka vm delete -v <NAME> -y
  1. List your VMs again.
orka vm list

You should see Deployed: 0 and Not Deployed: 1.

What's next

You're ready to explore the Orka CLI on your own. You might find the following resources helpful:

Updated 11 days ago


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.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


© 2019-2020 Copyright MacStadium, Inc. – Documentation built with readme.io. Orka is a registered trademark of MacStadium, Inc.