Command Reference

Anka CLI Command Reference

> sudo anka  --help
Usage: anka [OPTIONS] COMMAND [ARGS]...

Options:
  --machine-readable              JSON output format
  --log-level [debug|info|error]
  --debug
  -l, --login TEXT                Specify the vm policy user (if configured)
  --help                          Show this message and exit.

Commands:
  attach    Attach USB device(s) to running VM
  clone     Clones a VM
  config    Manage Anka configuration
  create    Creates a VM
  delete    Deletes a VM(s)
  describe  Shows VM configuration
  detach    Detach USB device(s) from the VM
  license   Licensing commands
  list      List VM library contents
  modify    Modifies a VM settings
  mount     Mounts local folder into VM
  reboot    Restarts a VM(s)
  registry  VMs registry
  run       Run commands inside VM environment
  show      Shows VM runtime properties
  start     Starts or resumes paused VM
  stop      Shuts down a VM(s)
  suspend   Suspends a VM(s)
  unmount   Unmount shared folder
  usb       Manage USB devices
  version   Prints out version
  view      Open VM display viewer

Attach

> sudo anka attach --help
Usage: anka attach [OPTIONS] VMID [DEVID]...

  Attach USB device(s) to running VM

Options:
  --help  Show this message and exit.

Clone

> sudo anka clone --help
Usage: anka clone [OPTIONS] VM_ID NEW_VM_NAME

  Clones a VM

Options:
  -c, --copy  Create independent copy instead of clone
  --help      Show this message and exit.

Config

> sudo anka config --help
Usage: anka config [OPTIONS] [PARAM]...

  Manage Anka configuration

Options:
  -l, --list                     List value parameter(s)
  -r, --reset                    Reset value of parameter(s)
  -s, --sorted / -S, --unsorted  Sort the output in alphabetical orders
  --help                         Show this message and exit.

Create

> sudo anka create --help
Usage: anka create [OPTIONS] VMNAME

  Creates a VM

Options:
  -m, --ram-size TEXT      ram size in G  [default: 4G]
  -c, --cpu-count INTEGER  the number of cpu cores  [default: 2]
  -d, --disk-size TEXT     sets the disk size when creating a new disk, G/M suffix needed  [default: 80G]
  -a, --app PATH           Path to Install macOS Application (downloadable from AppStore)
  -p, --pkg PATH           Additional package to be installed
  -s, --postinstall PATH   Postinstall scripts (to run with root credentials at first boot)
  -P, --profile PATH       Install configuration profile(s) alongside macOS installation
  --interactive            Perform default interactive installation instead of the automated one
  --help                   Show this message and exit.

Advanced usage guide for anka create

Delete

> sudo anka delete --help
Usage: anka delete [OPTIONS] [VMID]...

  Deletes a VM(s)

Options:
  --yes      Avoid asking of confirmation
  -a, --all  Delete all vms in library
  --help     Show this message and exit.

Describe

> sudo anka describe --help
Usage: anka describe [OPTIONS] VM_ID

  Shows VM configuration

Options:
  --help  Show this message and exit.

Detach

> sudo anka detach --help
Usage: anka detach [OPTIONS] VMID [DEVID]...

  Detach USB device(s) from the VM

Options:
  -a, --all  detach all devices from the vm
  --help     Show this message and exit.

License

> sudo anka license --help
Usage: anka license [OPTIONS] COMMAND [ARGS]...

  Licensing commands

Options:
  --help  Show this message and exit.

Commands:
  accept-eula  accept EULA (root privileges)
  activate     activate license key (root privileges)
  remove       removes the current license (root privileges)
  show         show license information
  validate     validates the current license

license accept-eula

> sudo anka license accept-eula --help
Usage: anka license accept-eula [OPTIONS]

  accept EULA (root privileges)

Options:
  --help  Show this message and exit.

license activate

> sudo anka license activate --help
Usage: anka license activate [OPTIONS] KEY

  activate license key (root privileges)

Options:
  -f, --force  silently override current license
  --cid TEXT   provide CustomerID
  --help       Show this message and exit.

license remove

> sudo anka license remove --help
Usage: anka license remove [OPTIONS]

  removes the current license (root privileges)

Options:
  --help  Show this message and exit.

license show

> sudo anka license show --help
Usage: anka license show [OPTIONS]

  show license information

Options:
  -k, --key TEXT  get key information
  --help          Show this message and exit.

To see current core consumption information for your license, use anka license show <licensekey>

license validate

> sudo anka license validate --help
Usage: anka license validate [OPTIONS]

  validates the current license

Options:
  --help  Show this message and exit.

List

> sudo anka list --help
Usage: anka list [OPTIONS] [VMID]...

  List VM library contents

Options:
  -r, --running     show only running vms
  -s, --stopped     show only stopped vms
  -f, --field TEXT  configure fields for each VM to be shown. Supported fields: name, version, uuid, creation_date,
                    status, stop_date, description, policy, cpu_cores, cpu_frequency, cpu_htt, ram, display.
  --help            Show this message and exit.

Modify

> sudo anka modify --help
Usage: anka modify [OPTIONS] VM_ID COMMAND [ARGS]...

  Modifies a VM settings

Options:
  --help  Show this message and exit.

Commands:
  add
  delete
  set
  show

modify {template} add

> sudo anka modify 10.15.4 add --help
Usage: anka modify add [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  hard-drive
  network-card
  optical-drive
  port-forwarding
  usb-device

modify {template} add hard-drive

> sudo anka modify 10.15.4 add hard-drive --help
Usage: anka modify add hard-drive [OPTIONS] ARGUMENT

Options:
  -f, --file  argument is path to external image or device
  -s, --size  argument is size (default)
  --help      Show this message and exit.

modify {template} add network-card

> sudo anka modify 10.15.4 add network-card --help
Usage: anka modify add network-card [OPTIONS]

Options:
  -t, --type [shared|host|bridge|disconnected]
                                  [default: shared]
  -b, --bridge TEXT               host interface name to bridge with (Wi-Fi not supported)
  -m, --mac TEXT                  assign fixed MAC address
  --help                          Show this message and exit.

modify {template} add optical-drive

> sudo anka modify 10.15.4 add optical-drive --help
Usage: anka modify add optical-drive [OPTIONS] ISO

Options:
  -f, --file  argument is path to external image or device (default)
  --help      Show this message and exit.

modify {template} add port-forwarding

> sudo anka modify 10.15.4 add port-forwarding --help
Usage: anka modify add port-forwarding [OPTIONS] RULE_NAME

Options:
  -p, --host-port INTEGER   the port to listen on the host
  -g, --guest-port INTEGER  the port to forward to on the vm  [required]
  -l, --host-ip TEXT        bind forwarding port to address, defaults to 0.0.0.0 (all)
  --guest-ip TEXT           specifies guest IP, in case the guest has multiple IPs
  --help                    Show this message and exit.

EXAMPLE - add port-forwarding

❯ sudo anka modify 10.15.4 add port-forwarding --guest-port 22 ssh

❯ sudo anka describe 10.15.4

. . .

port_forwarding_rules

+------------+--------------+-------------+------------+-----------+-------------+
|   net_card |   guest_port | rule_name   | protocol   |   host_ip |   host_port |
+============+==============+=============+============+===========+=============+
|          0 |           22 | ssh         | tcp        |         0 |           0 |
+------------+--------------+-------------+------------+-----------+-------------+

❯ sudo anka start 10.15.4
. . . 
port_forwarding

+--------------+-------------+------------+--------+-----------+
|   guest_port |   host_port | protocol   | name   | host_ip   |
+==============+=============+============+========+===========+
|           22 |       10000 | tcp        | ssh    | 0.0.0.0   |
+--------------+-------------+------------+--------+-----------+

❯ ssh anka@localhost -p 10000
Password:
Last login: Mon Apr  6 12:45:50 2020
Mac-mini:~ anka

Unless you customize the host_port, we default to using 10000, 10001, and so on for each VM that's started. Ensure that both the Controller server and any CI servers (where you host Jenkins for example) can reach the Node's ports in your firewall rules.

modify {template} add usb-device

> sudo anka modify 10.15.4 add usb-device --help
Usage: anka modify add usb-device [OPTIONS] [DEVICE]...

Options:
  -f, --force  skip device validation
  --help       Show this message and exit.

modify {template} delete

> sudo anka modify 10.15.4 delete --help
Usage: anka modify delete [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  custom-variable
  hard-drive
  network-card
  optical-drive
  policy
  port-forwarding
  usb-device

modify {template} delete custom-variable

> sudo anka modify 10.15.4 delete custom-variable --help
Usage: anka modify delete custom-variable [OPTIONS] KEY

Options:
  --help  Show this message and exit.

modify {template} delete hard-drive

> sudo anka modify 10.15.4 delete hard-drive --help
Usage: anka modify delete hard-drive [OPTIONS] [INDEX]...

Options:
  --help  Show this message and exit.

modify {template} delete network-card

> sudo anka modify 10.15.4 delete network-card --help
Usage: anka modify delete network-card [OPTIONS] [INDEX]...

Options:
  --help  Show this message and exit.

modify {template} delete optical-drive

> sudo anka modify 10.15.4 delete optical-drive --help
Usage: anka modify delete optical-drive [OPTIONS] [INDEX]...

Options:
  --help  Show this message and exit.

modify {template} delete policy

> sudo anka modify 10.15.4 delete policy --help
Usage: anka modify delete policy [OPTIONS]

Options:
  --help  Show this message and exit.

modify {template} delete port-forwarding

> sudo anka modify 10.15.4 delete port-forwarding --help
Usage: anka modify delete port-forwarding [OPTIONS] RULE_NAME

Options:
  --help  Show this message and exit.

modify {template} delete usb-device

> sudo anka modify 10.15.4 delete usb-device --help
Usage: anka modify delete usb-device [OPTIONS] [DEVICE]...

Options:
  --help  Show this message and exit.

modify {template} set

> sudo anka modify 10.15.4 set --help
Usage: anka modify set [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  cpu              set number of cpu cores and frequency
  custom-variable  configure variables
  description      set textual description of the VM
  display          configure displays
  hard-drive       modify hard drive settings
  name             set new name for the VM
  nested           enable nested virtualization
  network-card     modify network card settings
  policy           Enable VM access management
  ram              set RAM size and parameters

modify {template} set cpu

> sudo anka modify 10.15.4 set cpu --help
Usage: anka modify set cpu [OPTIONS] [NCPU]...

  set number of cpu cores and frequency

Options:
  -c, --cores INTEGER      number of cores
  -h, --htt / --no-htt     enable/disable hyper-threading
  -f, --frequency INTEGER  base CPU frequency (Hz)
  --help                   Show this message and exit.

modify {template} set custom-variable

> sudo anka modify 10.15.4 set custom-variable --help
Usage: anka modify set custom-variable [OPTIONS] KEY VALUE

  configure variables

Options:
  --help  Show this message and exit.

EXAMPLE - set custom-variable

sudo anka modify {template} set custom-variable hw.UUID "GUID"
sudo anka modify {template} set custom-variable hw.serial 'MySerial'

You can set the following custom variables:

boot-args - NVRAM boot arguments
hw.uuid - Hardware UUID
hw.serial - Serial Number (system)
hw.manufacturer - SMBIOS parameter (Reserved)
hw.product - SMBIOS parameter (Reserved)
hw.family - SMBIOS parameter (Reserved)
hw.board - SMBIOS parameter (Reserved)

modify {template} set description

> sudo anka modify 10.15.4 set description --help
Usage: anka modify set description [OPTIONS] TEXT

  set textual description of the VM

Options:
  --help  Show this message and exit.

modify {template} set display

> sudo anka modify 10.15.4 set display --help
Usage: anka modify set display [OPTIONS]

  configure displays

Options:
  -c, --count INTEGER    configure number of displays (2 max)
  --headless             same as --count 0
  -p, --password         prompt for VNC password
  -v, --vnc TEXT         configure VNC
  --no-vnc               disable VNC access to the VM
  -d, --dpi INTEGER      set DPI (default is 72)
  -r, --resolution TEXT  set resolution, e.g. 1024x768 or 'default' to reset to default
  --help                 Show this message and exit.

modify {template} set hard-drive

It's currently impossible to downsize an Anka VM's available space. We suggest creating your initial VM Template and Tag with a smaller amount of available disk and then increase in subsequent Tags.
> sudo anka modify 10.15.4 set hard-drive --help
Usage: anka modify set hard-drive [OPTIONS] [INDEX]...

  modify hard drive settings

Options:
  -s, --size TEXT                 Disk size
  -e, --enc [aes-128|aes-192|aes-256|none]
                                  Set OTFE algorithm
  --help                          Show this message and exit.

modify {template} set name

> sudo anka modify 10.15.4 set name --help
Usage: anka modify set name [OPTIONS] NAME

  set new name for the VM

Options:
  --help  Show this message and exit.

modify {template} set nested

> sudo anka modify 10.15.4 set nested --help
Usage: anka modify set nested [OPTIONS] NESTED

  enable nested virtualization

Options:
  --help  Show this message and exit.

modify {template} set network-card

> sudo anka modify 10.15.4 set network-card --help
Usage: anka modify set network-card [OPTIONS] [INDEX]...

  modify network card settings

Options:
  -t, --type [shared|host|bridge|disconnected]
  -b, --bridge TEXT               host interface name to bridge with (Wi-Fi is not supported)
  -m, --mac TEXT                  specify fixed MAC address
  -n, --no-mac                    deassign fixed MAC address
  --help                          Show this message and exit.

modify {template} set policy

> sudo anka modify 10.15.4 set policy --help
Usage: anka modify set policy [OPTIONS] [FILE]...

  Enable VM access management

Options:
  --help  Show this message and exit.

modify {template} set ram

> sudo anka modify 10.15.4 set ram --help
Usage: anka modify set ram [OPTIONS] [SIZE]...

  set RAM size and parameters

Options:
  --prefetch / --no-prefetch  enable/disable prefetch logic
  --help                      Show this message and exit.

modify {template} show

> sudo anka modify 10.15.4 show --help
Usage: anka modify show [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  custom-variables

modify {template} show custom-variables

> sudo anka modify 10.15.4 show custom-variables --help
Usage: anka modify show custom-variables [OPTIONS]

Options:
  --help  Show this message and exit.

Mount

> sudo anka mount --help
Usage: anka mount [OPTIONS] VMID [DIR]...

  Mounts local folder into VM

Options:
  --help  Show this message and exit.

Reboot

> sudo anka reboot --help
Usage: anka reboot [OPTIONS] [VMID]...

  Restarts a VM(s)

Options:
  -f, --force  flag. restarts the vm process
  -a, --all    reboot all running vms
  --help       Show this message and exit.

Registry

> sudo anka registry --help
Usage: anka registry [OPTIONS] COMMAND [ARGS]...

  VMs registry

Options:
  -r, --remote TEXT           Use repository name instead of 'default'
  -a, --registry-path TEXT    Use repository URL instead of 'default'
  -c, -i, --cert, --pem PATH  Client certificate if required
  -k, --key PATH              Private key, if the client certificate doesn't contain one
  --cacert, --root-cert PATH  Alternate ca_bundle
  --insecure                  Skip TLS verification
  --help                      Show this message and exit.

Commands:
  add                  Add repository
  check-download-size  Returns size of the data to be downloaded
  delete               Forget repository
  describe             Shows VM description
  list                 List VMs in repository
  list-repos           List registry repositories
  pull                 Pull certain VM
  push                 Push VM version (tag) to repository
  set                  Set default registry

registry add

> sudo anka registry add --help
Usage: anka registry add [OPTIONS] REG_NAME REG_URL

  Add repository

Options:
  --help  Show this message and exit.

registry check-download-size

> sudo anka registry check-download-size --help
Usage: anka registry check-download-size [OPTIONS] VM_ID

  Returns size of the data to be downloaded

Options:
  -t, --tag TEXT
  -v, --version INTEGER
  --help                 Show this message and exit.

registry delete

> sudo anka registry delete --help
Usage: anka registry delete [OPTIONS] [REMOTE]...

  Forget repository

Options:
  -a, --all  Forget all repositories
  --help     Show this message and exit.

registry describe

> sudo anka registry describe --help
Usage: anka registry describe [OPTIONS] VM_ID

  Shows VM description

Options:
  -t, --tag TEXT
  -v, --version INTEGER
  --help                 Show this message and exit.

registry list

> sudo anka registry list --help
Usage: anka registry list [OPTIONS] [VMID]...

  List VMs in repository

Options:
  --help  Show this message and exit.

registry list-repos

> sudo anka registry list-repos --help
Usage: anka registry list-repos [OPTIONS]

  List registry repositories

Options:
  -d, --default  show only default repository
  --help         Show this message and exit.

registry pull

> sudo anka registry pull --help
Usage: anka registry pull [OPTIONS] VM_ID

  Pull certain VM

Options:
  -t, --tag TEXT
  -v, --version INTEGER
  -l, --local            Switch to the local tag if exists
  -s, --shrink           Remove other local tags to optimize the footprint
  --help                 Show this message and exit.

registry push

> sudo anka registry push --help
Usage: anka registry push [OPTIONS] VM_ID [TAGNAME]...

  Push VM version (tag) to repository

Options:
  -t, --tag TEXT          Specify tag to push
  -d, --description TEXT  Assign description to the tag
  -v, --remote-vm TEXT    Push the tag to the remote vm specified
  -l, --local             Commit new tag only, don't upload
  --help                  Show this message and exit.

registry set

> sudo anka registry set --help
Usage: anka registry set [OPTIONS] REG_NAME

  Set default registry

Options:
  --help  Show this message and exit.

Run

> sudo anka run --help
Usage: anka run [OPTIONS] VM_NAME COMMAND [ARGS]...

  Run commands inside VM environment

Options:
  -w, --workdir PATH              Working directory inside the VM
  -v, --volumes-from, --volume PATH
                                  Mount host directory (current directory by default) into VM . '--volumes-from' is
                                  deprecated form
  -n, --no-volumes-from, --no-volume
                                  Use this flag to prevent implicit mounting of current folder (see --volume option).
                                  '--no-volumes-from' is deprecated form
  -E, -e, --env                   Inherit environment variables. '-e' is deprecated form
  -f, --env-file PATH             Provide environment variables from file
  -N, --wait-network              Wait till guest network interface up
  -T, --wait-time                 Wait for guest time sync
  --help                          Show this message and exit.

Show

> sudo anka show --help
Usage: anka show [OPTIONS] VM_ID [PROPERTY]...

  Shows VM runtime properties

Options:
  --help  Show this message and exit.

Start

> sudo anka start --help
Usage: anka start [OPTIONS] VM_ID

  Starts or resumes paused VM

Options:
  -u, --update-addons, --update  Run guest addons update procedure, previous version of the addons should be already
                                 installed
  -f, --force                    Start VM with minimum checks
  -v, --view                     Open display window
  -o, --optical-drive TEXT       Path to ISO file or device
  -d, --usb TEXT                 USB device ID/Location (should be claimed)
  --help                         Show this message and exit.

Stop

> sudo anka stop --help
Usage: anka stop [OPTIONS] [VMID]...

  Shuts down a VM(s)

Options:
  -f, --force  force the vm process to shut down
  -a, --all    Shutdown all running vms
  --help       Show this message and exit.

Suspend

> sudo anka suspend --help
Usage: anka suspend [OPTIONS] [VMID]...

  Suspends a VM(s)

Options:
  -a, --all  suspend all running vms
  --help     Show this message and exit.

Unmount

> sudo anka unmount --help
Usage: anka unmount [OPTIONS] VMID [DIR]...

  Unmount shared folder

Options:
  -a, --all  unmount all mounted folders
  --help     Show this message and exit.

Usb

> sudo anka usb --help
Usage: anka usb [OPTIONS] COMMAND [ARGS]...

  Manage USB devices

Options:
  --help  Show this message and exit.

Commands:
  claim    make a device(s) available for attaching to a...
  list     list available usb devices
  release  release a device(s) back to host availability

usb claim

> sudo anka usb claim --help
Usage: anka usb claim [OPTIONS] [DEVID]...

  make a device(s) available for attaching to a vm

Options:
  -n, --claim-name TEXT  claim name could be used as additional name
  --help                 Show this message and exit.

usb list

> sudo anka usb list --help
Usage: anka usb list [OPTIONS] [DEVID]...

  list available usb devices

Options:
  --help  Show this message and exit.

usb release

> sudo anka usb release --help
Usage: anka usb release [OPTIONS] [DEVID]...

  release a device(s) back to host availability

Options:
  -a, --all  release all devices
  --help     Show this message and exit.

Version

> sudo anka version --help
Usage: anka version [OPTIONS]

  Prints out version

Options:
  --help  Show this message and exit.

View

> sudo anka view --help
Usage: anka view [OPTIONS] VM_ID

  Open VM display viewer

Options:
  -d, --display INTEGER  Specify the displays to view
  -s, --screenshot       Make png screenshot
  -c, --click TEXT       Send the pointer event
  --help                 Show this message and exit.

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Last modified July 6, 2020 : note about disk reduction (f6b5bd4) by Nathan Pierce