Class: Bolt::BoltOptionParser
- Inherits:
-
OptionParser
- Object
- OptionParser
- Bolt::BoltOptionParser
- Defined in:
- lib/bolt/bolt_option_parser.rb
Constant Summary collapse
- OPTIONS =
{ inventory: %w[targets query rerun description], authentication: %w[user password password-prompt private-key host-key-check ssl ssl-verify], escalation: %w[run-as sudo-password sudo-password-prompt sudo-executable], run_context: %w[concurrency inventoryfile save-rerun], global_config_setters: %w[modulepath boltdir configfile], transports: %w[transport connect-timeout tty], display: %w[format color verbose trace], global: %w[help version debug] }.freeze
- ACTION_OPTS =
OPTIONS.values.flatten.freeze
- BANNER =
"NAME\n bolt\n\nUSAGE\n bolt <subcommand> [action] [options]\n\nDESCRIPTION\n Bolt is an orchestration tool that automates the manual work it takes to\n maintain your infrastructure.\n\nSUBCOMMANDS\n apply Apply Puppet manifest code\n command Run a command remotely\n file Upload a local file or directory\n group Show the list of groups in the inventory\n inventory Show the list of targets an action would run on\n plan Convert, show, and run Bolt plans\n project Create and migrate Bolt projects\n puppetfile Install and list modules and generate type references\n script Upload a local script and run it remotely\n secret Create encryption keys and encrypt and decrypt values\n task Show and run Bolt tasks\n"
- APPLY_HELP =
"NAME\n apply\n\nUSAGE\n bolt apply <manifest.pp> [options]\n\nDESCRIPTION\n Apply Puppet manifest code on the specified targets.\n\nEXAMPLES\n bolt apply manifest.pp --targets target1,target2\n"
- COMMAND_HELP =
"NAME\n command\n\nUSAGE\n bolt command <action> [options]\n\nDESCRIPTION\n Run a command on the specified targets.\n\nACTIONS\n run Run a command on the specified targets.\n"
- COMMAND_RUN_HELP =
"NAME\n run\n\nUSAGE\n bolt command run <command> [options]\n\nDESCRIPTION\n Run a command on the specified targets.\n\nEXAMPLES\n bolt command run 'uptime' -t target1,target2\n"
- FILE_HELP =
"NAME\n file\n\nUSAGE\n bolt file <action> [options]\n\nDESCRIPTION\n Upload a local file or directory\n\nACTIONS\n upload Upload a local file or directory\n"
- FILE_UPLOAD_HELP =
"NAME\n upload\n\nUSAGE\n bolt file upload <src> <dest> [options]\n\nDESCRIPTION\n Upload a local file or directory.\n\nEXAMPLES\n bolt file upload /tmp/source /etc/profile.d/login.sh -t target1\n"
- GROUP_HELP =
"NAME\n group\n\nUSAGE\n bolt group <action> [options]\n\nDESCRIPTION\n Show the list of groups in the inventory.\n\nACTIONS\n show Show the list of groups in the inventory\n"
- GROUP_SHOW_HELP =
"NAME\n show\n\nUSAGE\n bolt group show [options]\n\nDESCRIPTION\n Show the list of groups in the inventory.\n"
- INVENTORY_HELP =
"NAME\n inventory\n\nUSAGE\n bolt inventory <action> [options]\n\nDESCRIPTION\n Show the list of targets an action would run on.\n\nACTIONS\n show Show the list of targets an action would run on\n"
- INVENTORY_SHOW_HELP =
"NAME\n show\n\nUSAGE\n bolt inventory show [options]\n\nDESCRIPTION\n Show the list of targets an action would run on.\n"
- PLAN_HELP =
"NAME\n plan\n\nUSAGE\n bolt plan <action> [parameters] [options]\n\nDESCRIPTION\n Convert, show, and run Bolt plans.\n\nACTIONS\n convert Convert a YAML plan to a Bolt plan\n run Run a plan on the specified targets\n show Show available plans and plan documentation\n"
- PLAN_CONVERT_HELP =
"NAME\n convert\n\nUSAGE\n bolt plan convert <path> [options]\n\nDESCRIPTION\n Convert a YAML plan to a Bolt plan.\n\n Converting a YAML plan may result in a plan that is syntactically\n correct but has different behavior. Always verify a converted plan's\n functionality.\n\nEXAMPLES\n bolt plan convert path/to/plan/myplan.yaml\n"
- PLAN_RUN_HELP =
"NAME\n run\n\nUSAGE\n bolt plan run <plan> [parameters] [options]\n\nDESCRIPTION\n Run a plan on the specified targets.\n\nEXAMPLES\n bolt plan run canary --targets target1,target2 command=hostname\n"
- PLAN_SHOW_HELP =
"NAME\n show\n\nUSAGE\n bolt plan show [plan] [options]\n\nDESCRIPTION\n Show available plans and plan documentation.\n\n Omitting the name of a plan will display a list of plans available\n in the Bolt project.\n\n Providing the name of a plan will display detailed documentation for\n the plan, including a list of available parameters.\n\nEXAMPLES\n Display a list of available tasks\n bolt plan show\n Display documentation for the canary task\n bolt plan show aggregate::count\n"
- PROJECT_HELP =
"NAME\n project\n\nUSAGE\n bolt project <action> [options]\n\nDESCRIPTION\n Create and migrate Bolt projects\n\nACTIONS\n init Create a new Bolt project\n migrate Migrate a Bolt project to the latest version\n"
- PROJECT_INIT_HELP =
"NAME\n init\n\nUSAGE\n bolt project init [directory] [options]\n\nDESCRIPTION\n Create a new Bolt project.\n\n Specify a directory to create a Bolt project in. Defaults to the\n curent working directory.\n\nEXAMPLES\n Create a new Bolt project in the current working directory.\n bolt project init\n Create a new Bolt project at a specified path.\n bolt project init ~/path/to/project\n Create a new Bolt project with existing modules.\n bolt project init --modules puppetlabs-apt,puppetlabs-ntp\n"
- PROJECT_MIGRATE_HELP =
"NAME\n migrate\n\nUSAGE\n bolt project migrate [options]\n\nDESCRIPTION\n Migrate a Bolt project to the latest version.\n\n Loads a Bolt project's inventory file and migrates it to the latest version. The\n inventory file is modified in place and will not preserve comments or formatting.\n"
- PUPPETFILE_HELP =
"NAME\n puppetfile\n\nUSAGE\n bolt puppetfile <action> [options]\n\nDESCRIPTION\n Install and list modules and generate type references\n\nACTIONS\n generate-types Generate type references to register in plans\n install Install modules from a Puppetfile into a Boltdir\n show-modules List modules available to the Bolt project\n"
- PUPPETFILE_GENERATETYPES_HELP =
"NAME\n generate-types\n\nUSAGE\n bolt puppetfile generate-types [options]\n\nDESCRIPTION\n Generate type references to register in plans.\n"
- PUPPETFILE_INSTALL_HELP =
"NAME\n install\n\nUSAGE\n bolt puppetfile install [options]\n\nDESCRIPTION\n Install modules from a Puppetfile into a Boltdir\n"
- PUPPETFILE_SHOWMODULES_HELP =
"NAME\n show-modules\n\nUSAGE\n bolt puppetfile show-modules [options]\n\nDESCRIPTION\n List modules available to the Bolt project.\n"
- SCRIPT_HELP =
"NAME\n script\n\nUSAGE\n bolt script <action> [options]\n\nDESCRIPTION\n Run a script on the specified targets.\n\nACTIONS\n run Run a script on the specified targets.\n"
- SCRIPT_RUN_HELP =
"NAME\n run\n\nUSAGE\n bolt script run <script> [arguments] [options]\n\nDESCRIPTION\n Run a script on the specified targets.\n\n Arguments passed to a script are passed literally and are not interpolated\n by the shell. Any arguments containing spaces or special characters should\n be quoted.\n\nEXAMPLES\n bolt script run myscript.sh 'echo hello' --targets target1,target2\n"
- SECRET_HELP =
"NAME\n secret\n\nUSAGE\n bolt secret <action> [options]\n\nDESCRIPTION\n Create encryption keys and encrypt and decrypt values.\n\nACTIONS\n createkeys Create new encryption keys\n encrypt Encrypt a value\n decrypt Decrypt a value\n"
- SECRET_CREATEKEYS_HELP =
"NAME\n createkeys\n\nUSAGE\n bolt secret createkeys [options]\n\nDESCRIPTION\n Create new encryption keys.\n"
- SECRET_DECRYPT_HELP =
"NAME\n decrypt\n\nUSAGE\n bolt secret decrypt <ciphertext> [options]\n\nDESCRIPTION\n Decrypt a value.\n"
- SECRET_ENCRYPT_HELP =
"NAME\n encrypt\n\nUSAGE\n bolt secret encrypt <plaintext> [options]\n\nDESCRIPTION\n Encrypt a value.\n"
- TASK_HELP =
"NAME\n task\n\nUSAGE\n bolt task <action> [options]\n\nDESCRIPTION\n Show and run Bolt tasks.\n\nACTIONS\n run Run a Bolt task\n show Show available tasks and task documentation\n"
- TASK_RUN_HELP =
"NAME\n run\n\nUSAGE\n bolt task run <task> [parameters] [options]\n\nDESCRIPTION\n Run a task on the specified targets.\n\n Parameters take the form <parameter>=<value>.\n\nEXAMPLES\n bolt task run package --targets target1,target2 action=status name=bash\n"
- TASK_SHOW_HELP =
"NAME\n show\n\nUSAGE\n bolt task show [task] [options]\n\nDESCRIPTION\n Show available tasks and task documentation.\n\n Omitting the name of a task will display a list of tasks available\n in the Bolt project.\n\n Providing the name of a task will display detailed documentation for\n the task, including a list of available parameters.\n\nEXAMPLES\n Display a list of available tasks\n bolt task show\n Display documentation for the canary task\n bolt task show canary\n"
Instance Attribute Summary collapse
-
#warnings ⇒ Object
readonly
Returns the value of attribute warnings.
Instance Method Summary collapse
- #get_arg_input(value) ⇒ Object
- #get_help_text(subcommand, action = nil) ⇒ Object
-
#initialize(options) ⇒ BoltOptionParser
constructor
A new instance of BoltOptionParser.
- #parse_params(params) ⇒ Object
- #read_arg_file(file) ⇒ Object
- #remove_excluded_opts(option_list) ⇒ Object
- #update ⇒ Object
Constructor Details
#initialize(options) ⇒ BoltOptionParser
Returns a new instance of BoltOptionParser.
597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 |
# File 'lib/bolt/bolt_option_parser.rb', line 597 def initialize() super() = @warnings = [] separator "\nINVENTORY OPTIONS" define('-t', '--targets TARGETS', 'Identifies the targets of command.', 'Enter a comma-separated list of target URIs or group names.', "Or read a target list from an input file '@<file>' or stdin '-'.", 'Example: --targets localhost,target_group,ssh://nix.com:23,winrm://windows.puppet.com', 'URI format is [protocol://]host[:port]', "SSH is the default protocol; may be #{TRANSPORTS.keys.join(', ')}", 'For Windows targets, specify the winrm:// protocol if it has not be configured', 'For SSH, port defaults to `22`', 'For WinRM, port defaults to `5985` or `5986` based on the --[no-]ssl setting') do |targets| [:targets] ||= [] [:targets] << get_arg_input(targets) end define('-q', '--query QUERY', 'Query PuppetDB to determine the targets') do |query| [:query] = query end define('--rerun FILTER', 'Retry on targets from the last run', "'all' all targets that were part of the last run.", "'failure' targets that failed in the last run.", "'success' targets that succeeded in the last run.") do |rerun| [:rerun] = rerun end define('--noop', 'See what changes Bolt will make without actually executing the changes') do |_| [:noop] = true end define('--description DESCRIPTION', 'Description to use for the job') do |description| [:description] = description end define('--params PARAMETERS', "Parameters to a task or plan as json, a json file '@<file>', or on stdin '-'") do |params| [:task_options] = parse_params(params) end define('-e', '--execute CODE', "Puppet manifest code to apply to the targets") do |code| [:code] = code end define('--detail', 'Show resolved configuration for the targets') do |detail| [:detail] = detail end separator "\nAUTHENTICATION OPTIONS" define('-u', '--user USER', 'User to authenticate as') do |user| [:user] = user end define('-p', '--password PASSWORD', 'Password to authenticate with') do |password| [:password] = password end define('--password-prompt', 'Prompt for user to input password') do |_password| STDERR.print "Please enter your password: " [:password] = STDIN.noecho(&:gets).chomp STDERR.puts end define('--private-key KEY', 'Private ssh key to authenticate with') do |key| [:'private-key'] = key end define('--[no-]host-key-check', 'Check host keys with SSH') do |host_key_check| [:'host-key-check'] = host_key_check end define('--[no-]ssl', 'Use SSL with WinRM') do |ssl| [:ssl] = ssl end define('--[no-]ssl-verify', 'Verify remote host SSL certificate with WinRM') do |ssl_verify| [:'ssl-verify'] = ssl_verify end separator "\nESCALATION OPTIONS" define('--run-as USER', 'User to run as using privilege escalation') do |user| [:'run-as'] = user end define('--sudo-password PASSWORD', 'Password for privilege escalation') do |password| [:'sudo-password'] = password end define('--sudo-password-prompt', 'Prompt for user to input escalation password') do |_password| STDERR.print "Please enter your privilege escalation password: " [:'sudo-password'] = STDIN.noecho(&:gets).chomp STDERR.puts end define('--sudo-executable EXEC', "Specify an executable for running as another user.", "This option is experimental.") do |exec| [:'sudo-executable'] = exec end separator "\nRUN CONTEXT OPTIONS" define('-c', '--concurrency CONCURRENCY', Integer, 'Maximum number of simultaneous connections (default: 100)') do |concurrency| [:concurrency] = concurrency end define('--compile-concurrency CONCURRENCY', Integer, 'Maximum number of simultaneous manifest block compiles (default: number of cores)') do |concurrency| [:'compile-concurrency'] = concurrency end define('-m', '--modulepath MODULES', "List of directories containing modules, separated by '#{File::PATH_SEPARATOR}'", 'Directories are case-sensitive') do |modulepath| # When specified from the CLI, modulepath entries are relative to pwd [:modulepath] = modulepath.split(File::PATH_SEPARATOR).map do |moduledir| File.(moduledir) end end define('--boltdir FILEPATH', 'Specify what Boltdir to load config from (default: autodiscovered from current working dir)') do |path| [:boltdir] = path end define('--configfile FILEPATH', 'Specify where to load config from (default: ~/.puppetlabs/bolt/bolt.yaml).', 'Directory containing bolt.yaml will be used as the Boltdir.') do |path| [:configfile] = path end define('-i', '--inventoryfile FILEPATH', 'Specify where to load inventory from (default: ~/.puppetlabs/bolt/inventory.yaml)') do |path| if ENV.include?(Bolt::Inventory::ENVIRONMENT_VAR) raise Bolt::CLIError, "Cannot pass inventory file when #{Bolt::Inventory::ENVIRONMENT_VAR} is set" end [:inventoryfile] = Pathname.new(File.(path)) end define('--puppetfile FILEPATH', 'Specify a Puppetfile to use when installing modules. (default: ~/.puppetlabs/bolt/Puppetfile)', 'Modules are installed in the current Boltdir.') do |path| [:puppetfile_path] = Pathname.new(File.(path)) end define('--[no-]save-rerun', 'Whether to update the rerun file after this command.') do |save| [:'save-rerun'] = save end separator "\nTRANSPORT OPTIONS" define('--transport TRANSPORT', TRANSPORTS.keys.map(&:to_s), "Specify a default transport: #{TRANSPORTS.keys.join(', ')}") do |t| [:transport] = t end define('--connect-timeout TIMEOUT', Integer, 'Connection timeout (defaults vary)') do |timeout| [:'connect-timeout'] = timeout end define('--[no-]tty', 'Request a pseudo TTY on targets that support it') do |tty| [:tty] = tty end define('--tmpdir DIR', 'The directory to upload and execute temporary files on the target') do |tmpdir| [:tmpdir] = tmpdir end separator "\nDISPLAY OPTIONS" define('--filter FILTER', 'Filter tasks and plans by a matching substring') do |filter| unless /^[a-z0-9_:]+$/.match(filter) msg = "Illegal characters in filter string '#{filter}'. Filters must match a legal "\ "task or plan name." raise Bolt::CLIError, msg end [:filter] = filter end define('--format FORMAT', 'Output format to use: human or json') do |format| [:format] = format end define('--[no-]color', 'Whether to show output in color') do |color| [:color] = color end define('-v', '--[no-]verbose', 'Display verbose logging') do |value| [:verbose] = value end define('--trace', 'Display error stack traces') do |_| [:trace] = true end separator "\nADDITIONAL OPTIONS" define('--modules MODULES', 'A comma-separated list of modules to install from the Puppet Forge', 'when initializing a project. Resolves and installs all dependencies.') do |modules| [:modules] = modules.split(',') end separator "\nGLOBAL OPTIONS" define('-h', '--help', 'Display help') do |_| [:help] = true end define('--version', 'Display the version') do |_| puts Bolt::VERSION raise Bolt::CLIExit end define('--debug', 'Display debug logging') do |_| [:debug] = true end define('--plugin PLUGIN', 'Select the plugin to use') do |plug| [:plugin] = plug end end |
Instance Attribute Details
#warnings ⇒ Object (readonly)
Returns the value of attribute warnings.
596 597 598 |
# File 'lib/bolt/bolt_option_parser.rb', line 596 def warnings @warnings end |
Instance Method Details
#get_arg_input(value) ⇒ Object
820 821 822 823 824 825 826 827 828 829 |
# File 'lib/bolt/bolt_option_parser.rb', line 820 def get_arg_input(value) if value.start_with?('@') file = value.sub(/^@/, '') read_arg_file(file) elsif value == '-' STDIN.read else value end end |
#get_help_text(subcommand, action = nil) ⇒ Object
20 21 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 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 |
# File 'lib/bolt/bolt_option_parser.rb', line 20 def get_help_text(subcommand, action = nil) case subcommand when 'apply' { flags: ACTION_OPTS + %w[noop execute compile-concurrency], banner: APPLY_HELP } when 'command' case action when 'run' { flags: ACTION_OPTS, banner: COMMAND_RUN_HELP } else { flags: OPTIONS[:global], banner: COMMAND_HELP } end when 'file' case action when 'upload' { flags: ACTION_OPTS + %w[tmpdir], banner: FILE_UPLOAD_HELP } else { flags: OPTIONS[:global], banner: FILE_HELP } end when 'inventory' case action when 'show' { flags: OPTIONS[:inventory] + OPTIONS[:global] + %w[format inventoryfile boltdir configfile detail], banner: INVENTORY_SHOW_HELP } else { flags: OPTIONS[:global], banner: INVENTORY_HELP } end when 'group' case action when 'show' { flags: OPTIONS[:global] + %w[format inventoryfile boltdir configfile], banner: GROUP_SHOW_HELP } else { flags: OPTIONS[:global], banner: GROUP_HELP } end when 'plan' case action when 'convert' { flags: OPTIONS[:global] + OPTIONS[:global_config_setters], banner: PLAN_CONVERT_HELP } when 'run' { flags: ACTION_OPTS + %w[params compile-concurrency tmpdir], banner: PLAN_RUN_HELP } when 'show' { flags: OPTIONS[:global] + OPTIONS[:global_config_setters] + %w[filter format], banner: PLAN_SHOW_HELP } else { flags: OPTIONS[:global], banner: PLAN_HELP } end when 'project' case action when 'init' { flags: OPTIONS[:global] + %w[modules], banner: PROJECT_INIT_HELP } when 'migrate' { flags: OPTIONS[:global] + %w[inventoryfile boltdir configfile], banner: PROJECT_MIGRATE_HELP } else { flags: OPTIONS[:global], banner: PROJECT_HELP } end when 'puppetfile' case action when 'install' { flags: OPTIONS[:global] + OPTIONS[:global_config_setters] + %w[puppetfile], banner: PUPPETFILE_INSTALL_HELP } when 'show-modules' { flags: OPTIONS[:global] + OPTIONS[:global_config_setters], banner: PUPPETFILE_SHOWMODULES_HELP } when 'generate-types' { flags: OPTIONS[:global] + OPTIONS[:global_config_setters], banner: PUPPETFILE_GENERATETYPES_HELP } else { flags: OPTIONS[:global], banner: PUPPETFILE_HELP } end when 'script' case action when 'run' { flags: ACTION_OPTS + %w[tmpdir], banner: SCRIPT_RUN_HELP } else { flags: OPTIONS[:global], banner: SCRIPT_HELP } end when 'secret' case action when 'createkeys' { flags: OPTIONS[:global] + OPTIONS[:global_config_setters] + %w[plugin], banner: SECRET_CREATEKEYS_HELP } when 'decrypt' { flags: OPTIONS[:global] + OPTIONS[:global_config_setters] + %w[plugin], banner: SECRET_DECRYPT_HELP } when 'encrypt' { flags: OPTIONS[:global] + OPTIONS[:global_config_setters] + %w[plugin], banner: SECRET_ENCRYPT_HELP } else { flags: OPTIONS[:global], banner: SECRET_HELP } end when 'task' case action when 'run' { flags: ACTION_OPTS + %w[params tmpdir noop], banner: TASK_RUN_HELP } when 'show' { flags: OPTIONS[:global] + OPTIONS[:global_config_setters] + %w[filter format], banner: TASK_SHOW_HELP } else { flags: OPTIONS[:global], banner: TASK_HELP } end else { flags: OPTIONS[:global], banner: BANNER } end end |
#parse_params(params) ⇒ Object
813 814 815 816 817 818 |
# File 'lib/bolt/bolt_option_parser.rb', line 813 def parse_params(params) json = get_arg_input(params) JSON.parse(json) rescue JSON::ParserError => e raise Bolt::CLIError, "Unable to parse --params value as JSON: #{e}" end |
#read_arg_file(file) ⇒ Object
831 832 833 834 835 |
# File 'lib/bolt/bolt_option_parser.rb', line 831 def read_arg_file(file) File.read(File.(file)) rescue StandardError => e raise Bolt::FileError.new("Error attempting to read #{file}: #{e}", file) end |
#remove_excluded_opts(option_list) ⇒ Object
792 793 794 795 796 797 798 799 800 801 802 |
# File 'lib/bolt/bolt_option_parser.rb', line 792 def remove_excluded_opts(option_list) # Remove any options that are not available for the specified subcommand top.list.delete_if do |opt| opt.respond_to?(:switch_name) && !option_list.include?(opt.switch_name) end # Remove any separators if all options of that type have been removed top.list.delete_if do |opt| i = top.list.index(opt) opt.is_a?(String) && top.list[i + 1].is_a?(String) end end |
#update ⇒ Object
804 805 806 807 808 809 810 811 |
# File 'lib/bolt/bolt_option_parser.rb', line 804 def update help_text = get_help_text([:subcommand], [:action]) # Update the banner according to the subcommand self. = help_text[:banner] # Builds the option list for the specified subcommand and removes all excluded # options from the help text remove_excluded_opts(help_text[:flags]) end |