Class: Pvectl::Commands::SendkeyVm

Inherits:
Object
  • Object
show all
Defined in:
lib/pvectl/commands/sendkey_vm.rb

Overview

Handler for the ‘pvectl sendkey vm` command.

Sends a single QEMU monitor key event to a running VM. The key string uses QEMU’s qcode format (e.g., ctrl-alt-delete, ret, f1) and is forwarded verbatim to the Proxmox API.

Examples:

Send Ctrl+Alt+Delete to VM 100

pvectl sendkey vm 100 ctrl-alt-delete

Send Enter to VM 100

pvectl sendkey vm 100 ret

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args, options, global_options) ⇒ SendkeyVm

Initializes a sendkey VM command.

Parameters:

  • args (Array<String>) —

    command arguments

  • options (Hash) —

    command options

  • global_options (Hash) —

    global CLI options



106
107
108
109
110
 
# File 'lib/pvectl/commands/sendkey_vm.rb', line 106

def initialize(args, options, global_options)
  @args = Array(args)
  @options = options || {}
  @global_options = global_options || {}
end

Class Method Details

.execute(args, options, global_options) ⇒ Integer

Executes the sendkey VM command.

Parameters:

  • args (Array<String>) —

    command arguments (VMID KEY)

  • options (Hash) —

    command options

  • global_options (Hash) —

    global CLI options

Returns:

  • (Integer) —

    exit code



97
98
99
 
# File 'lib/pvectl/commands/sendkey_vm.rb', line 97

def self.execute(args, options, global_options)
  new(args, options, global_options).execute
end

.register(cli) ⇒ void

This method returns an undefined value.

Registers the sendkey command with the CLI.

Parameters:

  • cli (GLI::App) —

    the CLI application object



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/pvectl/commands/sendkey_vm.rb', line 22

def self.register(cli)
  cli.desc "Send a QEMU monitor key event to a VM"
  cli.long_desc <<~HELP
    Send a single QEMU monitor key event to a running virtual machine.
    The key string is forwarded verbatim to the Proxmox API and is
    interpreted by QEMU using its qcode key format.

    Common key codes:
      - ctrl-alt-delete    Reboot signal (Linux/Windows)
      - ctrl-alt-f1..f6    Switch Linux virtual terminals
      - ret                Enter / Return
      - esc                Escape
      - tab, spc, backspace

    Single character keys (letters, digits) are also accepted as-is.

    EXAMPLES
      Trigger Ctrl+Alt+Del on a running VM:
        $ pvectl sendkey vm 100 ctrl-alt-delete

      Send Enter (e.g., dismiss a bootloader prompt):
        $ pvectl sendkey vm 100 ret

      Send Escape:
        $ pvectl sendkey vm 100 esc

      Switch to TTY 1 on a Linux guest:
        $ pvectl sendkey vm 100 ctrl-alt-f1

      Resolve VM on a specific node:
        $ pvectl sendkey vm 100 ret --node pve1

    NOTES
      Only VMs are supported — LXC containers do not have a QEMU monitor.

      The VM must be running. If it is not, the command exits with an
      error before issuing the API call.

      Composite keys are dash-separated qcodes (e.g., "ctrl-alt-f1"),
      not the literal "+" notation. Refer to QEMU's qcode reference
      for the full list.

    SEE ALSO
      pvectl help console vm      Interactive console (recommended for
                                  sustained typing)
      pvectl help start           Start a stopped VM
  HELP
  cli.arg_name "RESOURCE_TYPE ID KEY"
  cli.command :sendkey do |c|
    c.desc "Node hosting the VM (used to disambiguate lookup)"
    c.flag [:node, :n], arg_name: "NODE"

    c.action do |global_options, options, args|
      resource_type = args.shift

      exit_code = case resource_type
      when "vm"
        SendkeyVm.execute(args, options, global_options)
      else
        $stderr.puts "Error: Unknown resource type: #{resource_type}"
        $stderr.puts "Valid types: vm"
        ExitCodes::USAGE_ERROR
      end

      exit exit_code if exit_code != 0
    end
  end
end

Instance Method Details

#execute ⇒ Integer

Executes the sendkey VM command.

Returns:

  • (Integer) —

    exit code



115
116
117
118
119
120
121
122
123
124
 
# File 'lib/pvectl/commands/sendkey_vm.rb', line 115

def execute
  vmid_arg = @args[0]
  key = @args[1]

  return usage_error("VMID is required") if vmid_arg.nil? || vmid_arg.to_s.strip.empty?
  return usage_error("VMID must be numeric: #{vmid_arg}") unless vmid_arg.to_s.match?(/\A\d+\z/)
  return usage_error("key argument is required") if key.nil? || key.to_s.strip.empty?

  perform_sendkey(vmid_arg.to_i, key)
end