MuranoCLI 3.0.1 → 3.0.2

data/lib/MrMurano/SolutionId.rb

@@ -1,4 +1,4 @@
-# Last Modified: 2017.08.23 /coding: utf-8
+# Last Modified: 2017.09.11 /coding: utf-8
 # frozen_string_literal: true
 
 # Copyright © 2016-2017 Exosite LLC.
@@ -9,68 +9,68 @@ require 'MrMurano/verbosing'
 
 module MrMurano
   module SolutionId
-    INVALID_SID = '-1'
+    INVALID_API_ID = '-1'
     UNEXPECTED_TYPE_OR_ERROR_MSG = (
       'Unexpected result type or error: assuming empty instead'
     )
 
+    attr_reader :api_id
+    attr_reader :valid_api_id
     attr_reader :sid
-    attr_reader :valid_sid
 
-    def init_sid!(sid=nil)
-      @valid_sid = false
+    def init_api_id!(api_id=nil)
+      @valid_api_id = false
       unless defined?(@solntype) && @solntype
         # Note that 'solution.id' isn't an actual config setting;
         # see instead 'application.id' and 'product.id'. We just
         # use 'solution.id' to indicate that the caller specified
         # a solution ID explicitly (i.e., it's not from the $cfg).
-        raise 'Missing sid or class @solntype!?' if sid.to_s.empty?
+        raise 'Missing api_id or class @solntype!?' if api_id.to_s.empty?
         @solntype = 'solution.id'
       end
-      if sid
-        self.sid = sid
+      if api_id
+        self.api_id = api_id
       else
         # Get the application.id or product.id.
-        self.sid = $cfg[@solntype]
+        self.api_id = $cfg[@solntype]
       end
       # Maybe raise 'No application!' or 'No product!'.
-      return unless @sid.to_s.empty?
+      return unless @api_id.to_s.empty?
       raise MrMurano::ConfigError.new("No #{/(.*).id/.match(@solntype)[1]} ID!")
     end
 
-    def sid?
-      # The @sid should never be nil or empty, but let's at least check.
-      @sid != INVALID_SID && !@sid.to_s.empty?
+    def api_id?
+      # The @api_id should never be nil or empty, but let's at least check.
+      @api_id != INVALID_API_ID && !@api_id.to_s.empty?
     end
 
-    def sid=(sid)
-      sid = INVALID_SID if sid.nil? || !sid.is_a?(String) || sid.empty?
-      if sid.to_s.empty? || sid == INVALID_SID || (defined?(@sid) && sid != @sid)
-        @valid_sid = false
+    def api_id=(api_id)
+      api_id = INVALID_API_ID if api_id.nil? || !api_id.is_a?(String) || api_id.empty?
+      if api_id.to_s.empty? || api_id == INVALID_API_ID || (defined?(@api_id) && api_id != @api_id)
+        @valid_api_id = false
       end
-      @sid = sid
-      # MAGIC_NUMBER: The 2nd element is the solution ID, e.g., solution/<sid>/...
-      raise "Unexpected @uriparts_sidex #{@uriparts_sidex}" unless @uriparts_sidex == 1
+      @api_id = api_id
+      # MAGIC_NUMBER: The 2nd element is the solution ID, e.g., solution/<api_id>/...
+      raise "Unexpected @uriparts_apidex #{@uriparts_apidex}" unless @uriparts_apidex == 1
       # We're called on initialize before @uriparts is built, so don't always do this.
-      @uriparts[@uriparts_sidex] = @sid if defined?(@uriparts)
+      @uriparts[@uriparts_apidex] = @api_id if defined?(@uriparts)
     end
 
     def affirm_valid
-      @valid_sid = true
+      @valid_api_id = true
     end
 
-    def valid_sid?
-      @valid_sid
+    def valid_api_id?
+      @valid_api_id
     end
 
-    # rubocop:disable Style/MethodName
-    def apiId
-      @sid
+    def api_id
+      @api_id
     end
 
     def endpoint(_path='')
       # This is hopefully just a DEV error, and not something user will ever see!
-      return unless @uriparts[@uriparts_sidex] == INVALID_SID
+      return unless @uriparts[@uriparts_apidex] == INVALID_API_ID
       error("Solution ID missing! Invalid #{MrMurano::Verbose.fancy_ticks(@solntype)}")
       exit 2
     end

data/lib/MrMurano/SyncUpDown.rb

@@ -1,4 +1,4 @@
-# Last Modified: 2017.08.23 /coding: utf-8
+# Last Modified: 2017.09.11 /coding: utf-8
 # frozen_string_literal: true
 
 # Copyright © 2016-2017 Exosite LLC.
@@ -295,17 +295,26 @@ module MrMurano
     #
     # @param local [Pathname] Full path of where to download to
     # @param item [Item] The item to download
-    def download(local, item)
+    def download(local, item, options={})
       #if item[:bundled]
       #  warning "Not downloading into bundled item #{synckey(item)}"
       #  return
       #end
       id = item[@itemkey.to_sym]
-      if id.nil?
-        debug "!!! Missing '#{@itemkey}', using :id instead!"
-        debug ":id => #{item[:id]}"
-        id = item[:id]
-        raise "Both #{@itemkey} and id in item are nil!" if id.nil?
+      if id.to_s.empty?
+        # 2017-09-05: MRMUR-156: User seeing this.
+        if @itemkey.to_sym != :id
+          debug "!!! Missing '#{@itemkey}', trying :id instead"
+          id = item[:id]
+        end
+        if id.to_s.empty?
+          debug %(Remote item "#{item[:name]}" missing :id / local: #{local} / item: #{item})
+          return if options[:ignore_errors]
+          error %(Remote item missing :id => #{local})
+          print %(You can ignore this error using --ignore-errors)
+          exit 1
+        end
+        debug ":id => #{id}"
       end
 
       relpath = local.relative_path_from(Pathname.pwd).to_s
@@ -400,14 +409,14 @@ module MrMurano
     end
 
     def syncup_before
-      syncable_validate_sid
+      syncable_validate_api_id
     end
 
     def syncup_after
     end
 
     def syncdown_before
-      syncable_validate_sid
+      syncable_validate_api_id
     end
 
     def syncdown_after(_local)
@@ -738,13 +747,13 @@ module MrMurano
       end
       toadd.each do |item|
         syncdown_item(item, into, options, :create, 'Adding') do |dest, aitem|
-          download(dest, aitem)
+          download(dest, aitem, options)
           num_synced += 1
         end
       end
       tomod.each do |item|
         syncdown_item(item, into, options, :update, 'Updating') do |dest, aitem|
-          download(dest, aitem)
+          download(dest, aitem, options)
           num_synced += 1
         end
       end
@@ -908,9 +917,10 @@ module MrMurano
       # Get the solution name from the config.
       # Convert, e.g., application.id => application.name
       soln_name = $cfg[@solntype.gsub(/(.*)\.id/, '\1.name')]
-      # Skip this syncable if the sid is not set, or if user wants to skip by solution.
+      # Skip this syncable if the api_id is not set, or if user wants to skip
+      # by solution.
       skip_sol = false
-      if !sid? ||
+      if !api_id? ||
          (options[:type] == :application && @solntype != 'application.id') ||
          (options[:type] == :product && @solntype != 'product.id')
         skip_sol = true
@@ -918,17 +928,17 @@ module MrMurano
         tested = false
         passed = false
         if @solntype == 'application.id'
-          # elevate_hash magically makes the hash return false rather than nil
-          # on unknown keys, so preface with a key? guard.
+          # elevate_hash makes the hash return false rather than
+          # nil on unknown keys, so preface with a key? guard.
           if options.key?(:application) && !options[:application].to_s.empty?
             if soln_name =~ /#{Regexp.escape(options[:application])}/i ||
-               sid =~ /#{Regexp.escape(options[:application])}/i
+               api_id =~ /#{Regexp.escape(options[:application])}/i
               passed = true
             end
             tested = true
           end
           if options.key?(:application_id) && !options[:application_id].to_s.empty?
-            passed = true if options[:application_id] == sid
+            passed = true if options[:application_id] == api_id
             tested = true
           end
           if options.key?(:application_name) && !options[:application_name].to_s.empty?
@@ -938,13 +948,13 @@ module MrMurano
         elsif @solntype == 'product.id'
           if options.key?(:product) && !options[:product].to_s.empty?
             if soln_name =~ /#{Regexp.escape(options[:product])}/i ||
-               sid =~ /#{Regexp.escape(options[:product])}/i
+               api_id =~ /#{Regexp.escape(options[:product])}/i
               passed = true
             end
             tested = true
           end
           if options.key?(:product_id) && !options[:product_id].to_s.empty?
-            passed = true if options[:product_id] == sid
+            passed = true if options[:product_id] == api_id
             tested = true
           end
           if options.key?(:product_name) && !options[:product_name].to_s.empty?
@@ -960,13 +970,13 @@ module MrMurano
       ret
     end
 
-    def syncable_validate_sid
+    def syncable_validate_api_id
       # 2017-07-02: Now that there are multiple solution types, and because
       # SyncRoot.add is called on different classes that go with either or
       # both products and applications, if a user only created one solution,
-      # then some syncables will have their sid set to -1, because there's
+      # then some syncables will have their api_id set to -1, because there's
       # not a corresponding solution in Murano.
-      raise 'Syncable missing sid or not valid_sid??!' unless sid?
+      raise 'Syncable missing api_id or not valid_api_id??!' unless api_id?
     end
 
     def items_lists(options, selected)

data/lib/MrMurano/Webservice-Endpoint.rb

@@ -1,4 +1,4 @@
-# Last Modified: 2017.08.22 /coding: utf-8
+# Last Modified: 2017.09.07 /coding: utf-8
 # frozen_string_literal: true
 
 # Copyright © 2016-2017 Exosite LLC.
@@ -108,6 +108,7 @@ module MrMurano
       # @param modify [Boolean] True if item exists already and this is changing it
       def upload(local, remote, _modify)
         local = Pathname.new(local) unless local.is_a? Pathname
+        # MAYBE/2017-09-07: Honor options.ignore_errors here?
         raise 'no file' unless local.exist?
         # we assume these are small enough to slurp.
         if remote.script.nil?

data/lib/MrMurano/Webservice.rb

@@ -1,4 +1,4 @@
-# Last Modified: 2017.08.16 /coding: utf-8
+# Last Modified: 2017.09.11 /coding: utf-8
 # frozen_string_literal: true
 
 # Copyright © 2016-2017 Exosite LLC.
@@ -22,11 +22,11 @@ module MrMurano
 
       def initialize
         @solntype = 'application.id'
-        @uriparts_sidex = 1
-        init_sid!
+        @uriparts_apidex = 1
+        init_api_id!
         # FIXME/2017-06-05/MRMUR-XXXX: Update to new endpoint.
-        #@uriparts = [:service, @sid, :webservice]
-        @uriparts = [:solution, @sid]
+        #@uriparts = [:service, @api_id, :webservice]
+        @uriparts = [:solution, @api_id]
         @itemkey = :id
         #@locationbase = $cfg['location.base']
         @location = nil

data/lib/MrMurano/commands.rb

@@ -1,4 +1,4 @@
-# Last Modified: 2017.08.16 /coding: utf-8
+# Last Modified: 2017.08.29 /coding: utf-8
 # frozen_string_literal: true
 
 # Copyright © 2016-2017 Exosite LLC.
@@ -17,6 +17,7 @@ require 'MrMurano/commands/content'
 require 'MrMurano/commands/cors'
 require 'MrMurano/commands/devices'
 require 'MrMurano/commands/domain'
+require 'MrMurano/commands/exchange'
 require 'MrMurano/commands/globals'
 require 'MrMurano/commands/keystore'
 require 'MrMurano/commands/init'

data/lib/MrMurano/commands/business.rb

@@ -1,4 +1,4 @@
-# Last Modified: 2017.08.23 /coding: utf-8
+# Last Modified: 2017.09.11 /coding: utf-8
 # frozen_string_literal: true
 
 # Copyright © 2016-2017 Exosite LLC.
@@ -12,8 +12,8 @@ require 'MrMurano/ReCommander'
 
 MSG_BUSINESSES_NONE_FOUND = 'No businesses found' unless defined? MSG_BUSINESSES_NONE_FOUND
 
-# *** Base business command help.
-# -------------------------------
+# *** Base business command help
+# ------------------------------
 
 command :business do |c|
   c.syntax = %(murano business)
@@ -31,16 +31,14 @@ Commands for working with businesses.
 end
 alias_command 'businesses', 'business'
 
-# *** Common business command options.
-# ------------------------------------
+# *** Common business command options
+# -----------------------------------
 
-def cmd_business_add_options(c)
+def cmd_table_output_add_options(c)
   # MAYBE/2017-08-15: Rename to --id-only.
   c.option '--idonly', 'Only return the IDs'
-  c.option '--[no-]brief', 'Show fewer fields: only Business ID and name'
-  # LATER/2017-08-17: Move -o to a file with --json, etc. (make
-  #   easier to use --json/--yaml/--output any file, without
-  #   having to use obscure `-c tool.outformat=json`).
+  c.option '--[no-]brief', 'Show fewer fields: show only IDs and names'
+  # MAYBE/2017-08-17: Move -o option to globals.rb and apply to all commands.
   c.option '-o', '--output FILE', 'Download to file instead of STDOUT'
 end
 
@@ -83,8 +81,8 @@ def any_business_pickers?(options)
   num_ways > 0
 end
 
-# *** Business commands: list and find.
-# -------------------------------------
+# *** Business commands: list and find
+# ------------------------------------
 
 command 'business list' do |c|
   c.syntax = %(murano business list [--options])
@@ -94,7 +92,7 @@ List businesses.
   ).strip
   c.project_not_required = true
 
-  cmd_business_add_options(c)
+  cmd_table_output_add_options(c)
 
   c.action do |args, options|
     c.verify_arg_count!(args)
@@ -111,7 +109,7 @@ Find business by name or ID.
   ).strip
   c.project_not_required = true
 
-  cmd_business_add_options(c)
+  cmd_table_output_add_options(c)
 
   # Add --business/-id/-name options.
   cmd_option_business_pickers(c)
@@ -130,8 +128,8 @@ Find business by name or ID.
   end
 end
 
-# *** Business actions helpers.
-# -----------------------------
+# *** Business actions helpers
+# ----------------------------
 
 def business_find_or_ask!(acc, options)
   #any_business_pickers?(options)
@@ -263,9 +261,9 @@ def cmd_business_find_businesses(acc, args, options)
   bizz
 end
 
-def cmd_business_output_businesses(acc, bizz, options)
+def cmd_business_header_and_bizz(bizz, options)
   if options.idonly
-    headers = [:bizid]
+    headers = %i[bizid]
     bizz = bizz.map(&:bizid)
   elsif options.brief
     #headers = %i[bizid role name]
@@ -274,7 +272,7 @@ def cmd_business_output_businesses(acc, bizz, options)
     bizz = bizz.map { |biz| [biz.bizid, biz.name] }
   else
     # 2017-08-16: There are only 3 keys: bizid, role, and name.
-    headers = bizz[0].meta.keys
+    headers = (bizz[0] && bizz[0].meta.keys) || []
     headers.sort_by! do |hdr|
       case hdr
       when :bizid
@@ -289,7 +287,11 @@ def cmd_business_output_businesses(acc, bizz, options)
     end
     bizz = bizz.map { |biz| headers.map { |key| biz.meta[key] } }
   end
+  [headers, bizz]
+end
 
+def cmd_business_output_businesses(acc, bizz, options)
+  headers, bizz = cmd_business_header_and_bizz(bizz, options)
   io = File.open(options.output, 'w') if options.output
   acc.outf(bizz, io) do |dd, ios|
     if options.idonly

data/lib/MrMurano/commands/domain.rb

@@ -1,4 +1,4 @@
-# Last Modified: 2017.08.16 /coding: utf-8
+# Last Modified: 2017.09.11 /coding: utf-8
 # frozen_string_literal: true
 
 # Copyright © 2016-2017 Exosite LLC.
@@ -41,7 +41,21 @@ Print the domain for this solution.
 
     solz.each do |sol|
       if !options.brief
-        say(sol.pretty_desc(add_type: true, raw_url: options.raw))
+        if $cfg['tool.outformat'] == 'best'
+          say(sol.pretty_desc(add_type: true, raw_url: options.raw))
+        else
+          dobj = {}
+          dobj[:type] = sol.type.to_s.capitalize
+          dobj[:name] = sol.name || ''
+          dobj[:api_id] = sol.api_id || ''
+          dobj[:sid] = sol.sid || ''
+          dobj[:domain] = ''
+          if sol.domain
+            dobj[:domain] += 'https://' unless options.raw
+            dobj[:domain] += sol.domain
+          end
+          sol.outf(dobj)
+        end
       elsif options.raw
         say(sol.domain)
       else

data/lib/MrMurano/commands/exchange.rb

@@ -0,0 +1,272 @@
+# Last Modified: 2017.08.31 /coding: utf-8
+# frozen_string_literal: true
+
+# Copyright © 2016-2017 Exosite LLC.
+# License: MIT. See LICENSE.txt.
+#  vim:tw=0:ts=2:sw=2:et:ai
+
+require 'highline'
+require 'MrMurano/verbosing'
+require 'MrMurano/Exchange'
+require 'MrMurano/ReCommander'
+require 'MrMurano/commands/business'
+
+# *** Business commands: Exchange Elements
+# ----------------------------------------
+
+command :exchange do |c|
+  c.syntax = %(murano exchange)
+  c.summary = %(About IOT Exchange)
+  c.description = %(
+Commands for working with IOT Exchange.
+  ).strip
+  c.project_not_required = true
+  c.subcmdgrouphelp = true
+
+  c.action do |_args, _options|
+    ::Commander::UI.enable_paging unless $cfg['tool.no-page']
+    say MrMurano::SubCmdGroupHelp.new(c).get_help
+  end
+end
+
+command 'exchange list' do |c|
+  c.syntax = %(murano exchange list [--options] [<name-or-ID>])
+  c.summary = %(List Exchange Elements)
+  c.description = %(
+List Exchange Elements, either all of them, or those that are purchased or available.
+
+Each Exchange Element is identified by an Element ID and a name.
+
+Element status:
+
+- added       An Element that has been added to and enabled for your Business
+
+- available   An Element that can be added to and enabled for your Business
+
+- available*  An Element that you can use if you upgrade your Business tier
+
+  ).strip
+  c.project_not_required = true
+
+  cmd_table_output_add_options(c)
+
+  c.option '--[no-]added', 'Only show Elements that have been added to the Application'
+  c.option '--[no-]full', 'Show all fields'
+  c.option '--[no-]other', 'Show other fields: like type, tiers, tags, and action, and apiServiceName'
+
+  # Add --id and --name options.
+  cmd_options_add_id_and_name(c)
+
+  c.action do |args, options|
+    c.verify_arg_count!(args, 1)
+    cmd_defaults_id_and_name(options)
+
+    xchg = MrMurano::Exchange.new
+
+    elems, available, purchased = find_elements(xchg, options, args[0])
+    if options.added.nil?
+      show = elems
+    elsif options.added
+      show = purchased
+    else
+      show = available
+    end
+
+    headers, pruned = cmd_exchange_header_and_elems(show, options)
+
+    io = File.open(options.output, 'w') if options.output
+    xchg.outf(pruned, io) do |item, ios|
+      if options.idonly
+        ios.puts item
+      else
+        ios.puts "Found #{pruned.length} elements."
+        xchg.tabularize(
+          {
+            headers: headers.map(&:to_s),
+            rows: item,
+          },
+          ios,
+        )
+      end
+    end
+    io.close unless io.nil?
+  end
+end
+alias_command 'exchange list available', 'exchange list', '--no-added'
+alias_command 'exchange list purchased', 'exchange list', '--added'
+
+def find_elements(xchg, options, term)
+  filter_id = nil
+  filter_name = nil
+  filter_fuzzy = nil
+  if term
+    if options.id
+      filter_id = term
+    elsif options.name
+      filter_name = term
+    else
+      filter_fuzzy = term
+    end
+  end
+  xchg.elements(filter_id: filter_id, filter_name: filter_name, filter_fuzzy: filter_fuzzy)
+end
+
+def cmd_exchange_header_and_elems(elems, options)
+  # MAYBE/2017-08-31: If you `-c outformat=json`, each Element is a
+  # list of values, rather than a dictionary. Wouldn't the JSON be
+  # easier to consume if each Element was a dict, rather than list?
+  if options.idonly
+    headers = %i[elementId]
+    elems = elems.map(&:elementId)
+  elsif options.brief
+    headers = %i[elementId name]
+    headers += [:status] unless options.added
+    #elems = elems.map { |elem| [elem.elementId, elem.name] }
+    elems = elems.map { |elem| headers.map { |key| elem.send(key) } }
+  elsif options.full
+    headers = %i[elementId name status type apiServiceName tiers tags actions markdown]
+    all_hdrs = (elems[0] && elems[0].meta.keys) || []
+    all_hdrs.each do |chk|
+      headers.push(chk) unless headers.include?(chk)
+    end
+    #elems = elems.map { |elem| headers.map { |key| elem.meta[key] } }
+    elems = elems.map { |elem| headers.map { |key| elem.send(key) || '' } }
+  elsif options.other
+    # NOTE: Showing columns not displayed when --other not specified,
+    #   except not showing :markdown, ever.
+    headers = %i[elementId type apiServiceName tiers tags actions]
+    #headers = %i[elementId type apiServiceName tiers tags actions markdown]
+    #elems = elems.map { |elem| headers.map { |key| elem.send(key) } }
+    elems = elems.map do |elem|
+      [
+        elem.elementId,
+        elem.type,
+        elem.apiServiceName,
+        #elem.tiers,
+        #elem.tiers.join(' | '),
+        elem.tiers.join("\n"),
+        #elem.tags,
+        #elem.tags.join(' | '),
+        elem.tags.join("\n"),
+        #elem.actions,
+        elem.actions.map { |actn| actn.map { |key, val| "#{key}: #{val}" }.join("\n") }.join("\n"),
+        #elem.markdown.gsub("\n", '\\n'),
+      ]
+    end
+  else
+    # 2017-08-28: There are 9 keys, and one of them -- :markdown -- is a
+    # lot of text, so rather than, e.g., elems[0].meta.keys, be selective.
+    headers = %i[elementId name]
+    headers += [:status] unless options.added
+    headers += [:description]
+    if $stdout.tty?
+      # Calculate how much room (how many characters) are left for the
+      # description column.
+      width_taken = 0
+      # rubocop:disable Performance/FixedSize
+      #   "Do not compute the size of statically sized objects."
+      width_taken += '| '.length
+      # Calculate the width of each column except the last (:description).
+      headers[0..-2].each do |key|
+        elem_with_max = elems.max { |a, b| a.send(key).length <=> b.send(key).length }
+        width_taken += elem_with_max.send(key).length
+        width_taken += ' | '.length
+      end
+      width_taken += ' | '.length
+      term_width, _rows = HighLine::SystemExtensions.terminal_size
+      width_avail = term_width - width_taken
+      # MAGIC_NUMBER: Tweak/change this if you want. 20 char min feels
+      # about right: don't wrap if column would be narrow or negative.
+      width_avail = nil if width_avail < 20
+    else
+      width_avail = nil
+    end
+    #elems = elems.map { |elem| headers.map { |key| elem.send(key) } }
+    elems = elems.map do |elem|
+      headers.map do |key|
+        if !width_avail.nil? && key == :description
+          #elem.meta[key].scan(/.{1,#{width_avail}}/).join("\n")
+          full = elem.send(key)
+          parts = []
+          until full.empty?
+            # Split the description on a space before the max width.
+            # FIXME/2017-08-28: Need to test really long desc with no space.
+            part = full[0..width_avail]
+            full = full[(width_avail + 1)..-1] || ''
+            leftover = ''
+            part, _space, leftover = part.rpartition(' ') unless full.empty?
+            if part.empty?
+              part = leftover.to_s
+              leftover = ''
+            else
+              full = leftover.to_s + full
+              full = full
+            end
+            parts.push(part.strip)
+          end
+          parts.join("\n")
+        else
+          elem.send(key)
+        end
+      end
+    end
+  end
+  [headers, elems]
+end
+
+command 'exchange purchase' do |c|
+  c.syntax = %(murano exchange purchase [--options] <name-or-ID>)
+  c.summary = %(Add an Exchange Element to your Business)
+  c.description = %(
+Add an Exchange Element to your Business.
+  ).strip
+  # It feels a little weird to not require a project, but all
+  # we need is the Business ID; this action does not apply to
+  # solutions.
+  c.project_not_required = true
+
+  # Add --id and --name options.
+  cmd_options_add_id_and_name(c)
+
+  c.action do |args, options|
+    c.verify_arg_count!(args, 1, ['Missing Element name or ID'])
+    cmd_defaults_id_and_name(options)
+
+    xchg = MrMurano::Exchange.new
+
+    # If the user specifies filter_id, we could try to fetch that Element
+    # directly (e.g., by calling exchange/<bizId>/element/<elemId>),
+    # but the response doesn't specify if the Element is purchased or not.
+    # So we grab everything from /element/ and /purchase/.
+
+    elems, _available, purchased = find_elements(xchg, options, args[0])
+    if elems.length > 1
+      idents = elems.map { |elem| "#{xchg.fancy_ticks(elem.name)} (#{elem.elementId})" }
+      idents[-1] = 'and ' + idents[-1]
+      xchg.warning(
+        'Please be more specific: More than one matching element was found: ' \
+        "#{idents.join(', ')}"
+      )
+      exit 2
+    elsif elems.empty?
+      xchg.warning('No matching element was found.')
+      exit 2
+    elsif purchased.length == 1
+      # I.e., elems.status == :added
+      xchg.warning(
+        'The specified element has already been purchased: ' \
+        "#{xchg.fancy_ticks(purchased[0].name)} (#{purchased[0].elementId})"
+      )
+      exit 2
+    elsif elems.first.status == :upgrade
+      xchg.warning('Please upgrade your Business to add this Element. Visit:')
+      xchg.warning('  https://www.exosite.io/business/settings/upgrade')
+      exit 2
+    end
+
+    xchg.purchase(elems.first.elementId)
+  end
+end
+alias_command 'exchange add', 'exchange purchase'
+alias_command 'exchange buy', 'exchange purchase'
+