collins-cli 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 087cbec35df74ca5deb78665d0d40547483968d3
-  data.tar.gz: dcc8cc251bc58b3e6ca6df9881de6eeffef00caf
+  metadata.gz: 9d8cb9285558a8adc49d7da521c0241e1331eb08
+  data.tar.gz: 27559afb065f378b3e60aa010eb3271e40e53222
 SHA512:
-  metadata.gz: 5d3b4860eede427118996a3740233e494df10b0bc46c94a2394f01d78fb1d20b3796a528d8353900bb8774f655f7bf9e86d24594c331b7fa56ac22b71471b319
-  data.tar.gz: 19aa32592ffcf6cac34565ae87ca37bcd35c7ecc182138c2464bcceba65898258ac25fb11853f3d29fb627fe16c589fe5824bba081c7e60e6e70ff7857a6a4a8
+  metadata.gz: b96eda4857aaed7c4a92a704306ff7158f322f3708e24cb66fd15a9665977827d6620fec9244fff7496bf8217445144695d1058e935522504de95fc00f8d50f1
+  data.tar.gz: 050ca2a0dfddb04dd02c798bcd58fad07078e5445e37f0fb8337360928fb95ea2c7f3518fd293acbeec5da10011296b119b1b4516992adad21f8ec0e8e5b5b1a

data/README.md

@@ -7,18 +7,34 @@ CLI scripts for interacting with Collins API
 
 ## Overview
 
-Main entry point is the ```collins``` binary.
+```collins-cli``` uses the ```collins_auth``` gem for authentication, so it relies on you either typing in your credentials every time, or setting up a ~/.collins.yml file. The base format for the config file is as follows:
 
+    ---
+    host: https://collins.iata.company.com
+    username: myuser
+    # omit password to have collins auth prompt you
+    password: mypass
+
+(see https://github.com/tumblr/collins/tree/master/support/ruby/collins-auth for more details)
+
+Main entry point is the ```collins``` binary:
+
+    $ collins -h
     Usage: collins <command> [options]
     Available commands:
       query, find:        Search for assets in Collins
       modify, set:        Add and remove attributes, change statuses, and log to assets
       log:                Display log messages on assets
-      provision, action:  Provision, control power status, allocate IPs, update IPMI info
+      provision:          Provision assets
+      power:              Control and show power status
+      ip, address, ipmi:  Allocate IPs, update IPMI info
 
-## Searching - collins-find
+## Find Assets - collins find
 
-    Usage: collins-find [options] [hostnamepattern]
+Use ```collins find``` to quickly construct complex queries of your assets in Collins. Bonus points for piping the output of ```collins find``` into another program.
+
+    $ collins find -h
+    Usage: collins find [options] [hostnamepattern]
     Query options:
         -t, --tag TAG[,...]              Assets with tag[s] TAG
         -T, --type TYPE                  Only show assets with type TYPE
@@ -61,7 +77,9 @@ Main entry point is the ```collins``` binary.
         Query for all develnode6 nodes with a value for PUPPET_SERVER
           cf -n develnode6 -a puppet_server -H
 
-## Logging - collins-log
+## View Logs - collins log
+
+Pipe the output of ```collins find``` into ```collins log``` to pull recent logs, or tail logs. Very useful while watching provisioning. Reads asset tags from ARGF if ```--tags``` aren't provided.
 
     Usage: collins-log [options]
         -a, --all                        Show logs from ALL assets
@@ -87,9 +105,11 @@ Main entry point is the ```collins``` binary.
       Show last 10 logs for all web nodes that are provisioned having verification in the message
         cf -S provisioned -n webnode$ | collins-log -n10 -s debug | grep -i verification
 
-## Modification - collins-modify
+## Modification - collins modify
 
-    Usage: collins-modify [options]
+Pipe the output of ```collins find``` into ```collins modify``` to change statuses, create and delete attributes, write log messages, etc. Reads asset tags from ARGF if ```--tags``` aren't provided.
+
+    Usage: collins modify [options]
         -a attribute:value,              Set attribute=value. : between key and value. attribute will be uppercased.
             --set-attribute
         -d, --delete-attribute attribute Delete attribute.
@@ -116,33 +136,31 @@ Main entry point is the ```collins``` binary.
     
     Examples:
       Set an attribute on some hosts:
-        collins-modify -t 001234,004567 -a my_attribute:true
+        collins modify -t 001234,004567 -a my_attribute:true
       Delete an attribute on some hosts:
-        collins-modify -t 001234,004567 -d my_attribute
+        collins modify -t 001234,004567 -d my_attribute
       Delete and add attribute at same time:
-        collins-modify -t 001234,004567 -a new_attr:test -d old_attr
+        collins modify -t 001234,004567 -a new_attr:test -d old_attr
       Set machine into maintenace noop:
-        collins-modify -t 001234 -S maintenance:maint_noop -r "I do what I want"
+        collins modify -t 001234 -S maintenance:maint_noop -r "I do what I want"
       Set machine back to allocated:
-        collins-modify -t 001234 -S allocated:running -r "Back to allocated"
+        collins modify -t 001234 -S allocated:running -r "Back to allocated"
       Set machine back to new without setting state:
-        collins-modify -t 001234 -S new -r "Dunno why you would want this"
+        collins modify -t 001234 -S new -r "Dunno why you would want this"
       Create a log entry:
-        collins-modify -t 001234 -l'computers are broken and everything is horrible' -Lwarning
+        collins modify -t 001234 -l'computers are broken and everything is horrible' -Lwarning
       Read from stdin:
-        cf -n develnode | collins-modify -d my_attribute
-        cf -n develnode -S allocated | collins-modify -a collectd_version:5.2.1-52
-        echo -e "001234\n001235\n001236"| collins-modify -a test_attribute:'hello world'
+        cf -n develnode | collins modify -d my_attribute
+        cf -n develnode -S allocated | collins modify -a collectd_version:5.2.1-52
+        echo -e "001234\n001235\n001236"| collins modify -a test_attribute:'hello world'
 
-## Actions - collins-action
+## Provision - collins provision
+
+Pipe the output of ```collins find``` into ```collins provision``` to provision assets. Reads asset tags from ARGF if ```--tags``` aren't provided.
+
+    $ collins provision -h
+    Usage: collins provision [options]
 
-    Usage: collins-action [options]
-    Actions:
-        -P, --provision                  Provision assets (see Provisioning flags).
-        -S, --power-status               Show IPMI power status.
-        -A, --power-action ACTION        Perform IPMI power ACTION on assets
-    
-    Provisioning Flags:
         -n, --nodeclass NODECLASS        Nodeclass to provision as. (Required)
         -p, --pool POOL                  Provision with pool POOL.
         -r, --role ROLE                  Provision with primary role ROLE.
@@ -150,6 +168,25 @@ Main entry point is the ```collins``` binary.
         -s, --suffix SUFFIX              Provision with suffix SUFFIX.
         -a, --activate                   Activate server on provision (useful with SL plugin) (Default: ignored)
         -b, --build-contact USER         Build contact. (Default: gabe)
+
+    General:
+        -t, --tags TAG[,...]             Tags to work on, comma separated
+        -C, --config CONFIG              Use specific Collins config yaml for Collins::Client
+        -h, --help                       Help
+
+    Examples:
+      Provision some machines:
+        collins find -Sunallocated -arack_position:716|collins provision -P -napiwebnode6 -RALL
+
+## Power Management - collins power
+
+Manage and show power states with ```collins power```
+
+    $ collins power -h
+    Usage: collins power [options]
+    
+        -s, --status                     Show IPMI power status
+        -p, --power ACTION               Perform IPMI power ACTION
     
     General:
         -t, --tags TAG[,...]             Tags to work on, comma separated
@@ -157,17 +194,39 @@ Main entry point is the ```collins``` binary.
         -h, --help                       Help
     
     Examples:
-      Provision some machines:
-        cf -Sunallocated -arack_position:716|collins-action -P -napiwebnode6 -RALL
-      Show power status:
-        cf ^dev6-gabe|collins-action -S
-      Power cycle a bunch of machines:
-        collins-action -t 001234,004567,007890 -A reboot
+      Reset some machines:
+        collins power -t 001234,003456,007895 -p reboot
 
-## TODO
+## IPAM - collins ip
+
+Allocate and delete addresses, and show what address pools are configured in Collins.
 
-I know the architecture is BRUTAL. This was all organically created; I need to refactor stuff out into libraries to facilitate code sharing between the utilities
+    Usage: collins ipam [options]
+    
+        -s, --show-pools                 Show IP pools
+        -H, --show-header                Show header fields in --show-pools output
+        -a, --allocate POOL              Allocate addresses in POOL
+        -n, --number [NUM]               Allocate NUM addresses (Defaults to 1 if omitted)
+        -d, --delete [POOL]              Delete addresses in POOL. Deletes ALL addresses if POOL is omitted
+    
+    General:
+        -t, --tags TAG[,...]             Tags to work on, comma separated
+        -C, --config CONFIG              Use specific Collins config yaml for Collins::Client
+        -h, --help                       Help
+    
+    Examples:
+      Show configured IP address pools:
+        collins ipam --show-pools -H
+      Allocate 2 IPs on each asset
+        collins ipam -t 001234,003456,007895 -a DEV_POOL -n2
+      Deallocate IPs in DEV_POOL pool on assets:
+        collins ipam -t 001234,003456,007895 -d DEV_POOL
+      Deallocate ALL IPs on assets:
+        collins ipam -t 001234,003456,007895 -d
+
+## TODO
 
-* Implement IP allocation in collins-action
-* Implement IPMI stuff in collins-action
-* Share code between binaries
+* Implement IP allocation in collins-ipam
+* Implement IPMI stuff in collins-ipmi
+* Share code between binaries more
+* Write some tests

data/bin/collins

@@ -1,21 +1,40 @@
 #!/usr/bin/env ruby
+require 'collins-cli'
 
 ALLOWED_ACTIONS = {
-  :find => ['query','find'],
-  :modify => ['modify','set'],
-  :log => ['log'],
-  :action => ['provision','action']
+  Collins::CLI::Find => ['query','find'],
+  Collins::CLI::Modify => ['modify','set'],
+  Collins::CLI::Log => ['log'],
+  Collins::CLI::Provision => ['provision'],
+  Collins::CLI::Power => ['power'],
+  Collins::CLI::IPAM => ['ipam','address','ipaddress'],
 }
-action = ARGV.shift
-target,_ = ALLOWED_ACTIONS.select {|k,v| v.any? {|handle| ! %r|^#{action}|.match(handle).nil? } }.first
-if action.nil? || target.nil?
-  abort <<_MESSAGE_
-Usage: #{File.basename(File.realpath($0))} <command> [options]
+
+HELP_MESSAGE = "Usage: #{File.basename(File.realpath($0))} <command> [options]
 Available commands:
-  query, find:        Search for assets in Collins
-  modify, set:        Add and remove attributes, change statuses, and log to assets
-  log:                Display log messages on assets
-  provision, action:  Provision, control power status, allocate IPs, update IPMI info
-_MESSAGE_
+  query, find:               Search for assets in Collins
+  modify, set:               Add and remove attributes, change statuses, and log to assets
+  log:                       Display log messages on assets
+  provision:                 Provision assets
+  power:                     Control and show power status
+  ipam, address, ipaddress:  Allocate and delete IPs, show IP pools"
+
+abort HELP_MESSAGE if ARGV.empty?
+action = ARGV.shift
+targets = ALLOWED_ACTIONS.select {|k,v| v.any? {|handle| ! %r|^#{action}|.match(handle).nil? } }
+target,_ = targets.first
+if ['-h','--help'].include? action
+  puts HELP_MESSAGE
+  exit 0
+elsif targets.empty? or target.nil?
+  abort ["Unknown action #{action}!","",HELP_MESSAGE].join("\n")
+elsif targets.length > 1
+  abort ["Action #{action} was ambiguous! Please be more specific (i.e. type the whole action out)","",HELP_MESSAGE].join("\n")
+end
+
+begin
+  exit target.new.parse!.validate!.run!
+rescue => e
+  abort e.message
+  #raise e
 end
-exec File.join(__dir__,"collins-#{target}"), *ARGV

data/lib/collins/cli/find.rb

@@ -0,0 +1,161 @@
+require 'collins-cli'
+
+#TODO: querying for :status or :state with -a status:maintenance doesnt play nice with -Smaintenance,allocated
+#TODO: we construct the query for states and statuses only from the parameters to --status (ignoring any -a attributes)
+
+module Collins::CLI
+  class Find
+    include Mixins
+    include Formatter   # how to display assets
+
+    PROG_NAME = 'collins find'
+    QUERY_DEFAULTS = {
+      :operation => 'AND',
+      :size => 9999,
+    }
+    OPTION_DEFAULTS = {
+      :format          => :table,           # how to display the results
+      :separator        => "\t",
+      :attributes       => {},            # additional attributes to query for
+      :columns          => [:tag, :hostname, :nodeclass, :status, :pool, :primary_role, :secondary_role],
+      :column_override  => [],       # if set, these are the columns to display
+      :timeout          => 120,
+      :show_header      => false,        # if the header for columns should be displayed
+      :config           => nil           # collins config to give to setup_client
+    }
+
+    attr_reader :options, :query_opts, :search_attrs, :parser
+
+    def initialize
+      @parsed, @validated = false, false
+      @query_opts = QUERY_DEFAULTS.clone
+      @search_attrs = {}
+      @options = OPTION_DEFAULTS.clone
+      @parser = nil
+    end
+
+    def parse!(argv = ARGV)
+      raise "See --help for #{PROG_NAME} usage" if argv.empty?
+      @parser = OptionParser.new do |opts|
+        opts.banner = "Usage: #{PROG_NAME} [options] [hostnamepattern]"
+        opts.separator "Query options:"
+        opts.on('-t','--tag TAG[,...]',Array, "Assets with tag[s] TAG") {|v| search_attrs[:tag] = v}
+        opts.on('-T','--type TYPE',String, "Only show assets with type TYPE") {|v| search_attrs[:type] = v}
+        opts.on('-n','--nodeclass NODECLASS[,...]',Array, "Assets in nodeclass NODECLASS") {|v| search_attrs[:nodeclass] = v}
+        opts.on('-p','--pool POOL[,...]',Array, "Assets in pool POOL") {|v| search_attrs[:pool] = v}
+        opts.on('-s','--size SIZE',Integer, "Number of assets to return (Default: #{query_opts[:size]})") {|v| query_opts[:size] = v}
+        opts.on('-r','--role ROLE[,...]',Array,"Assets in primary role ROLE") {|v| search_attrs[:primary_role] = v}
+        opts.on('-R','--secondary-role ROLE[,...]',Array,"Assets in secondary role ROLE") {|v| search_attrs[:secondary_role] = v}
+        opts.on('-i','--ip-address IP[,...]',Array,"Assets with IP address[es]") {|v| search_attrs[:ip_address] = v}
+        opts.on('-S','--status STATUS[:STATE][,...]',Array,"Asset status (and optional state after :)") do |v|
+          # in order to know what state was paired with what status, lets store the original params
+          # so the query constructor can create the correct CQL query
+          options[:status_state] = v
+          search_attrs[:status], search_attrs[:state] = v.inject([[],[]]) do |memo,s|
+            status,state = s.split(':')
+            memo[0] << status.upcase if not status.nil? and not status.empty?
+            memo[1] << state.upcase if not state.nil? and not state.empty?
+            memo
+          end
+        end
+        opts.on('-a','--attribute attribute[:value[,...]]',String,"Arbitrary attributes and values to match in query. : between key and value") do |x|
+          x.split(',').each do |p|
+            a,v = p.split(':')
+            a = a.to_sym
+            if not search_attrs[a].nil? and not search_attrs[a].is_a? Array
+              # its a single value, turn it into an array
+              search_attrs[a] = [search_attrs[a]]
+            end
+            if search_attrs[a].is_a? Array
+              # already multivalue, append
+              search_attrs[a] << v
+            else
+              search_attrs[a] = v
+            end
+          end
+        end
+
+        opts.separator ""
+        opts.separator "Table formatting:"
+        opts.on('-H','--show-header',"Show header fields in output") {options[:show_header] = true}
+        opts.on('-c','--columns ATTRIBUTES',Array,"Attributes to output as columns, comma separated (Default: #{options[:columns].map(&:to_s).join(',')})") {|v| options[:column_override] = v.map(&:to_sym)}
+        opts.on('-x','--extra-columns ATTRIBUTES',Array,"Show these columns in addition to the default columns, comma separated") {|v| options[:columns].push(v.map(&:to_sym)).flatten! }
+        opts.on('-f','--field-separator SEPARATOR',String,"Separator between columns in output (Default: #{options[:separator]})") {|v| options[:separator] = v}
+
+        opts.separator ""
+        opts.separator "Robot formatting:"
+        opts.on('-l','--link',"Output link to assets found in web UI") {options[:format] = :link}
+        opts.on('-j','--json',"Output results in JSON (NOTE: This probably wont be what you expected)") {options[:format] = :json}
+        opts.on('-y','--yaml',"Output results in YAML") {options[:format] = :yaml}
+
+        opts.separator ""
+        opts.separator "Extra options:"
+        opts.on('--expire SECONDS',Integer,"Timeout in seconds (0 == forever)") {|v| options[:timeout] = v}
+        opts.on('-C','--config CONFIG',String,'Use specific Collins config yaml for Collins::Client') {|v| options[:config] = v}
+        opts.on('-h','--help',"Help") {options[:mode] = :help}
+
+        opts.separator ""
+        opts.separator <<_EXAMPLES_
+Examples:
+    Query for devnodes in DEVEL pool that are VMs
+      cf -n develnode -p DEVEL
+    Query for asset 001234, and show its system_password
+      cf -t 001234 -x system_password
+    Query for all decommissioned VM assets
+      cf -a is_vm:true -S decommissioned
+    Query for hosts matching hostname '^web6-'
+      cf ^web6-
+    Query for all develnode6 nodes with a value for PUPPET_SERVER
+      cf -n develnode6 -a puppet_server -H
+_EXAMPLES_
+      end
+      @parser.parse!(argv)
+      # hostname is the final option, no flags
+      search_attrs[:hostname] = argv.shift
+      @parsed = true
+      self
+    end
+
+    def validate!
+      raise "Options not yet parsed with #parse!" unless @parsed
+      # fix bug where assets wont get found if they dont have that meta attribute
+      search_attrs.delete(:hostname) if search_attrs[:hostname].nil?
+      # for any search attributes, lets not pass arrays of 1 element
+      # as that will confuse as_query?
+      search_attrs.each do |k,v|
+        if v.is_a? Array
+          search_attrs[k] = v.first if v.length == 1
+          search_attrs[k] = nil if v.empty?
+        end
+      end
+
+      # merge search_attrs into query
+      if as_query?(search_attrs)
+        query_opts[:query] = convert_to_query(query_opts[:operation], search_attrs, options)
+      else
+        query_opts.merge!(search_attrs)
+      end
+      @validated = true
+      self
+    end
+
+    def run!
+      raise "Options not yet parsed with #parse!" unless @parsed
+      raise "Options not yet validated with #validate!" unless @validated
+      if options[:mode] == :help
+        puts parser
+      else
+        begin
+          assets = collins.find(query_opts)
+        rescue => e
+          raise "Error querying collins: #{e.message}"
+        end
+        format_assets(assets, options)
+      end
+      true
+    end
+
+  end
+end
+
+

data/lib/collins/cli/formatter.rb

@@ -0,0 +1,74 @@
+require 'collins-cli'
+
+module Collins::CLI::Formatter
+  FORMATTING_DEFAULTS = {
+    :format           => :table,           # how to display the results
+    :separator        => "\t",
+    :columns          => [:tag, :hostname, :nodeclass, :status, :pool, :primary_role, :secondary_role],
+    :column_override  => [],       # if set, these are the columns to display
+    :show_header      => false,        # if the header for columns should be displayed
+  }
+  ADDRESS_POOL_COLUMNS = [:name, :network, :start_address, :specified_gateway, :gateway, :broadcast, :possible_addresses]
+
+  def format_pools(pools, opts = {})
+    if pools.length > 0
+      opts = FORMATTING_DEFAULTS.merge(opts)
+      # map the hashes into openstructs that will respond to #send(:name)
+      ostructs = pools.map { |p| OpenStruct.new(Hash[p.map {|k,v| [k.downcase,v]}]) }
+      display_as_table(ostructs, ADDRESS_POOL_COLUMNS, opts[:separator], opts[:show_header])
+    else
+      raise "No pools found"
+    end
+  end
+
+  def format_assets(assets, opts = {})
+    opts = FORMATTING_DEFAULTS.merge(opts)
+    if assets.length > 0
+      case opts[:format]
+      when :table
+        # if the user passed :column_override, respect that absolutely. otherwise, the columns to display
+        # should be opts[:columns] + any extra attributes queried for. this way ```cf -c hostname -a is_vm:true```
+        # wont return 2 columns; only the one you asked for
+        columns = if opts[:column_override].empty?
+                    opts[:columns].concat(search_attrs.keys).compact.uniq
+                  else
+                    opts[:column_override]
+                  end
+        display_as_table(assets,columns,opts[:separator],opts[:show_header])
+      when :link
+        display_as_link assets, collins
+      when :json,:yaml
+        display_as_robot_talk(assets,opts[:format])
+      else
+        raise "I don't know how to display assets in #{opts[:format]} format!"
+      end
+    else
+      raise "No assets found"
+    end
+  end
+
+  def display_as_robot_talk(assets, format = :json)
+    puts assets.send("to_#{format}".to_sym)
+  end
+  def display_as_table(assets, columns, separator, show_header = false)
+    # lets figure out how wide each column is, including header
+    column_width_pairs = columns.map do |column|
+      # grab all attributes == column and figure out max width
+      width = assets.map{|a| (column == :state) ?  a.send(column).label.to_s.length : a.send(column).to_s.length}.max
+      width = [width, column.to_s.length].max if show_header
+      [column,width]
+    end
+    column_width_map = Hash[column_width_pairs]
+    if show_header
+      $stderr.puts column_width_map.map{|c,w| "%-#{w}s" % c}.join(separator)
+    end
+    assets.each do |a|
+      puts column_width_map.map {|c,w| v = (c == :state) ?  a.send(c).label : a.send(c) ; "%-#{w}s" % v }.join(separator)
+    end
+  end
+  def display_as_link assets, client
+    assets.each do |a|
+      puts "#{client.host}/asset/#{a.tag}"
+    end
+  end
+end

data/lib/collins/cli/ipam.rb

@@ -0,0 +1,99 @@
+require 'collins-cli'
+
+module Collins::CLI
+  class IPAM
+    include Mixins
+    include Formatter
+    PROG_NAME = 'collins ipam'
+
+    DEFAULT_OPTIONS = {
+      :timeout => 120,
+      :mode => nil,
+      :show_header => false,
+      :num => 1,
+      :tags => [],
+    }
+
+    attr_reader :options, :parser
+
+    def initialize
+      @options = DEFAULT_OPTIONS.clone
+      @parsed, @validated = false, false
+      @parser = nil
+    end
+
+    def parse!(argv = ARGV)
+      @parser = OptionParser.new do |opts|
+        opts.banner = "Usage: #{PROG_NAME} [options]"
+        opts.separator ""
+        opts.on('-s','--show-pools',"Show IP pools") {|v| @options[:mode] = :show }
+        opts.on('-H','--show-header',"Show header fields in --show-pools output") {|v| @options[:show_header] = true }
+        opts.on('-a','--allocate POOL',String,"Allocate addresses in POOL") {|v| @options[:mode] = :allocate ; @options[:pool] = v }
+        opts.on('-n','--number [NUM]',Integer,"Allocate NUM addresses (Defaults to 1 if omitted)") {|v| @options[:num] = v || 1 }
+        opts.on('-d','--delete [POOL]',String,"Delete addresses in POOL. Deletes ALL addresses if POOL is omitted") {|v| @options[:mode] = :delete ; @options[:pool] = v }
+
+        opts.separator ""
+        opts.separator "General:"
+        opts.on('-t','--tags TAG[,...]',Array,"Tags to work on, comma separated") {|v| @options[:tags] = v.map(&:to_sym)}
+        opts.on('-C','--config CONFIG',String,'Use specific Collins config yaml for Collins::Client') {|v| @options[:config] = v}
+        opts.on('-h','--help',"Help") {@options[:mode] = :help}
+
+        opts.separator ""
+        opts.separator "Examples:"
+        opts.separator "  Show configured IP address pools:"
+        opts.separator "    #{PROG_NAME} --show-pools -H"
+        opts.separator "  Allocate 2 IPs on each asset"
+        opts.separator "    #{PROG_NAME} -t 001234,003456,007895 -a DEV_POOL -n2"
+        opts.separator "  Deallocate IPs in DEV_POOL pool on assets:"
+        opts.separator "    #{PROG_NAME} -t 001234,003456,007895 -d DEV_POOL"
+        opts.separator "  Deallocate ALL IPs on assets:"
+        opts.separator "    #{PROG_NAME} -t 001234,003456,007895 -d"
+      end
+      @parser.parse!(argv)
+
+      # only read tags from ARGF if we are going to do something with the tags
+      if [:allocate,:delete].include? options[:mode] && (options[:tags].nil? or options[:tags].empty?)
+        # read tags from stdin. first field on the line is the tag
+        input = ARGF.readlines
+        @options[:tags] = input.map{|l| l.split(/\s+/)[0] rescue nil}.compact.uniq
+      end
+      @parsed = true
+      self
+    end
+
+    def validate!
+      raise "You need to tell me to do something!" if @options[:mode].nil?
+      raise "No asset tags found via ARGF" if [:allocate,:delete].include?(options[:mode]) && (options[:tags].nil? or options[:tags].empty?)
+      @validated = true
+      self
+    end
+
+    def run!
+      raise "Options not yet parsed with #parse!" unless @parsed
+      raise "Options not yet validated with #validate!" unless @validated
+      success = true
+      case options[:mode]
+      when :help
+        puts parser
+      when :show
+        pools = collins.ipaddress_pools
+        format_pools(pools, :show_header => options[:show_header])
+      when :allocate
+        options[:tags].each do |t|
+          res = api_call("allocating #{options[:num]} IP in #{options[:pool]}",:ipaddress_allocate!,t,options[:pool],options[:num]) do |addresses|
+            "Allocated #{addresses.map(&:address).join(' ')}"
+          end
+          success = false unless res
+        end
+      when :delete
+        options[:tags].each do |t|
+          res = api_call("deleting all IPs#{" in #{options[:pool]}" unless options[:pool].nil?}",:ipaddress_delete!,t,options[:pool]) { |count| "Deleted #{count} IPs" }
+          success = false unless res
+        end
+      end
+      success
+    end
+
+  end
+end
+