Class: VagrantPlugins::OrbStack::Util::OrbStackCLI

Inherits:
Object
  • Object
show all
Defined in:
lib/vagrant-orbstack/util/orbstack_cli.rb

Overview

Utility class for detecting and interacting with OrbStack CLI

This class provides a Ruby interface to the OrbStack command-line tool (orb). All methods execute shell commands and return parsed results. The class handles timeouts, error detection, and logging automatically.

Examples:

Check if OrbStack is available

if OrbStackCLI.available?
  puts "OrbStack version: #{OrbStackCLI.version}"
end

Create and manage a machine

OrbStackCLI.create_machine('ubuntu', 'my-dev-vm')
OrbStackCLI.start_machine('my-dev-vm')
info = OrbStackCLI.machine_info('my-dev-vm')
OrbStackCLI.stop_machine('my-dev-vm')

List all machines

machines = OrbStackCLI.list_machines
machines.each do |m|
  puts "#{m[:name]} - #{m[:status]}"
end

Constant Summary collapse

QUERY_TIMEOUT =

Default timeout for non-mutating query operations (list, info). Use this for fast read operations.

Returns:

  • (Integer) —

    Timeout in seconds

30
MUTATE_TIMEOUT =

Default timeout for state-changing operations (start, stop, delete). Use this for operations that modify machine state.

Returns:

  • (Integer) —

    Timeout in seconds

60
CREATE_TIMEOUT =

Default timeout for machine creation operations. Longer timeout accounts for distribution image downloads which can take 30-120 seconds on first use.

Returns:

  • (Integer) —

    Timeout in seconds

120

Class Method Summary collapse

Class Method Details

.available? ⇒ Boolean

Check if orb command is available in PATH

Returns:

  • (Boolean) —

    true if orb command exists, false otherwise



55
56
57
58
 
# File 'lib/vagrant-orbstack/util/orbstack_cli.rb', line 55

def available?
  stdout, _stderr, success = execute_command('which orb')
  !stdout.empty? && success
end

.create_machine(name, distribution:, timeout: CREATE_TIMEOUT) ⇒ Hash

Create a new OrbStack machine

Executes orb create <distro> <name>. This operation can take 30-120 seconds on first use if the distribution image needs to be downloaded. Subsequent creations of the same distribution are much faster.

rubocop:disable Naming/PredicateMethod

Examples:

Create an Ubuntu machine

OrbStackCLI.create_machine('my-dev-vm', distribution: 'ubuntu:noble')

Create with custom timeout for slow networks

OrbStackCLI.create_machine('my-vm', distribution: 'ubuntu', timeout: 180)

Parameters:

  • name (String) —

    The machine name

  • distribution (String) —

    The distribution to use (e.g., 'ubuntu:noble', 'debian')

  • timeout (Integer) (defaults to: CREATE_TIMEOUT) —

    Command timeout in seconds (default: CREATE_TIMEOUT)

Returns:

  • (Hash) —

    Machine info hash with :id and :status keys

Raises:



156
157
158
159
160
 
# File 'lib/vagrant-orbstack/util/orbstack_cli.rb', line 156

def create_machine(name, distribution:, timeout: CREATE_TIMEOUT)
  _, stderr, success = execute_command("orb create #{distribution} #{name}", timeout: timeout)
  raise_unless_successful!('create', stderr, success)
  { id: name, status: 'running' }
end

.delete_machine(name) ⇒ Boolean

Delete an OrbStack machine

Executes orb delete <name>. This permanently removes the machine and all its data. The operation cannot be undone.

Examples:

Delete a machine

OrbStackCLI.delete_machine('my-dev-vm')

Parameters:

  • name (String) —

    The machine name

Returns:

  • (Boolean) —

    true on success

Raises:



174
175
176
177
178
 
# File 'lib/vagrant-orbstack/util/orbstack_cli.rb', line 174

def delete_machine(name)
  _, stderr, success = execute_command("orb delete #{name}", timeout: MUTATE_TIMEOUT)
  raise_unless_successful!('delete', stderr, success)
  true
end

.list_machines ⇒ Array<Hash>, Array

List all OrbStack machines

Executes orb list and parses the output into an array of machine hashes. Each hash contains the machine name and current status.

rubocop:disable Metrics/MethodLength

Examples:

List all machines

machines = OrbStackCLI.list_machines
# => [{name: 'ubuntu-dev', status: 'running'}, {name: 'debian-test', status: 'stopped'}]

Returns:

  • (Array<Hash>) —

    Array of machine hashes, each with:

    • :name [String] The machine name
    • :status [String] The machine status (e.g., 'running', 'stopped')
  • (Array) —

    Empty array on failure or if no machines exist

Raises:



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/vagrant-orbstack/util/orbstack_cli.rb', line 93

def list_machines
  stdout, _stderr, success = execute_command('orb list', timeout: QUERY_TIMEOUT)
  return [] unless success
  return [] if stdout.empty?

  # Parse machine list output (format: NAME STATUS DISTRO IP)
  machines = []
  stdout.each_line do |line|
    parts = line.strip.split(/\s+/)
    next if parts.empty?

    machines << {
      name: parts[0],
      status: parts[1]
    }
  end

  machines
end

.machine_info(name) ⇒ Hash?

Get detailed information about a specific machine

Executes orb info <name> and parses the JSON output. Returns nil if the machine doesn't exist or if JSON parsing fails.

Examples:

Get machine info

info = OrbStackCLI.machine_info('my-dev-vm')
puts info['distro'] if info

Parameters:

  • name (String) —

    The machine name

Returns:

  • (Hash, nil) —

    Parsed machine information hash with OrbStack-specific fields, or nil if machine not found or parsing fails

Raises:



127
128
129
130
131
132
133
134
135
 
# File 'lib/vagrant-orbstack/util/orbstack_cli.rb', line 127

def machine_info(name)
  stdout, _stderr, success = execute_command("orb info --format json #{name}", timeout: QUERY_TIMEOUT)
  return nil unless success

  JSON.parse(stdout)
rescue JSON::ParserError => e
  @logger.warn("Failed to parse machine info JSON: #{e.message}")
  nil
end

.running? ⇒ Boolean

Check if OrbStack is currently running

Returns:

  • (Boolean) —

    true if running, false otherwise



73
74
75
76
 
# File 'lib/vagrant-orbstack/util/orbstack_cli.rb', line 73

def running?
  stdout, _stderr, success = execute_command('orb status')
  success && stdout.match?(/running/i)
end

.start_machine(name, timeout: MUTATE_TIMEOUT) ⇒ Hash

Start an OrbStack machine

Executes orb start <name>. Starts a stopped machine. If the machine is already running, this is a no-op.

Examples:

Start a machine

OrbStackCLI.start_machine('my-dev-vm')

Parameters:

  • name (String) —

    The machine name

  • timeout (Integer) (defaults to: MUTATE_TIMEOUT) —

    Command timeout in seconds (default: MUTATE_TIMEOUT)

Returns:

  • (Hash) —

    Machine info hash with :id and :status keys

Raises:



193
194
195
196
197
 
# File 'lib/vagrant-orbstack/util/orbstack_cli.rb', line 193

def start_machine(name, timeout: MUTATE_TIMEOUT)
  _, stderr, success = execute_command("orb start #{name}", timeout: timeout)
  raise_unless_successful!('start', stderr, success)
  { id: name, status: 'running' }
end

.stop_machine(name) ⇒ Boolean

Stop an OrbStack machine

Executes orb stop <name>. Stops a running machine gracefully. If the machine is already stopped, this is a no-op.

Examples:

Stop a machine

OrbStackCLI.stop_machine('my-dev-vm')

Parameters:

  • name (String) —

    The machine name

Returns:

  • (Boolean) —

    true on success

Raises:



211
212
213
214
215
 
# File 'lib/vagrant-orbstack/util/orbstack_cli.rb', line 211

def stop_machine(name)
  _, stderr, success = execute_command("orb stop #{name}", timeout: MUTATE_TIMEOUT)
  raise_unless_successful!('stop', stderr, success)
  true
end

.version ⇒ String?

Get OrbStack version

Returns:

  • (String, nil) —

    version string or nil if not available



62
63
64
65
66
67
68
69
 
# File 'lib/vagrant-orbstack/util/orbstack_cli.rb', line 62

def version
  stdout, _stderr, success = execute_command('orb --version')
  return nil unless success

  # Parse version from output like "orb version 1.2.3" or just "1.2.3"
  match = stdout.match(/(\d+\.\d+\.\d+)/)
  match ? match[1] : nil
end