locd 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: eb0dc7c5d3b58d3a71a6f37ca805ad663a503d47
-  data.tar.gz: 0c4c9fe5124b32cdc7774b956bc44b95e80891c5
+  metadata.gz: 630061e7d172448491a1da49c70cfac510519d26
+  data.tar.gz: 417ac04a01d1bc9e6e888f3e8a1e847407d7b017
 SHA512:
-  metadata.gz: 51ec7cb0807e43bebe247e25854e8a2037f524d542b7d55bd6f40433704e3c354c4859335b5c48b72a908dca41fec8f56ccad955bd65a844a6d9e13269ff886b
-  data.tar.gz: e9e9309a808d16576fc38826a73b6f9034ce870be0b34871f57c360d398d736e61a9508ac2fb46a68f8e6c07925d38e8af334303f8c3e942b6ae4521ba992d7e
+  metadata.gz: f3bf11b09b944869c254175fd90984f54959596c9506220d9a79ec49fe6a4ee7d7beb355bff2773b6db552d7bec74f69d3e1c3fb7a313550790ff3334384f72e
+  data.tar.gz: 5c03efd66d67973b72a2608ee21c695b2e9aa473c7f9659c713da8a13736799e8941406a2c4d5b2f24ddcfff56915badb785c5ef7c949c580c728d3b49e3d5e5

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.1.4

data/exe/locd

@@ -13,12 +13,4 @@ logger = SemanticLogger[__FILE__]
 
 require 'locd/cli'
 
-begin
-  Locd::CLI::Command::Main.start
-rescue Exception => e
-  if e.instance_of?(SystemExit)
-    raise
-  else
-    logger.fatal e
-  end
-end
+Locd::CLI::Command::Main.exec!

data/lib/locd/agent.rb

@@ -40,14 +40,6 @@ class Locd::Agent
   # Constants
   # ==========================================================================
   
-  # Extra plist key we store Loc'd config under (this is where the port is
-  # stored). We also use it's presence to detect that a plist is Loc'd.
-  # 
-  # @return [String]
-  # 
-  CONFIG_KEY = 'locd_config'
-  
-  
   # Attribute / method names that {#to_h} uses.
   # 
   # @return [Hamster::SortedSet<Symbol>]
@@ -69,7 +61,7 @@ class Locd::Agent
   # ==========================================================================
   
   # Test if the parse of a property list is for a Loc'd agent by seeing if
-  # it has {CONFIG_KEY} as a key.
+  # it has the config key (from `Locd.config[:agent, :config_key]`) as a key.
   # 
   # @param [Hash<String, Object>] plist
   #   {include:file:doc/include/plist.md}
@@ -78,7 +70,7 @@ class Locd::Agent
   #   `true` if the plist looks like it's from Loc'd.
   # 
   def self.plist? plist
-    plist.key? CONFIG_KEY
+    plist.key? Locd.config[:agent, :config_key]
   end # .plist?
   
   
@@ -351,7 +343,7 @@ class Locd::Agent
   # Parameters are passed to {Locd::Label.regexp_for_glob} and the resulting
   # {Regexp} is matched against each agent's {#label}.
   # 
-  # @see Locd::Label.regexp_for_glob
+  # @see Locd::Pattern
   # 
   # @param (see .find_all)
   # 
@@ -364,7 +356,7 @@ class Locd::Agent
   
   # Find all the agents that match a pattern.
   # 
-  # @see Locd::Label.regexp_for_glob
+  # @see Locd::Pattern
   # 
   # @param [String | Pattern] pattern
   #   Pattern to match against agent.
@@ -539,7 +531,7 @@ class Locd::Agent
       
       # Extras we need... `launchd` complains in the system log about this
       # but it's the easiest way to handle it at the moment
-      CONFIG_KEY => {
+      Locd.config[:agent, :config_key] => {
         # Save this too why the hell not, might help debuging at least
         cmd_template: cmd_template,
         
@@ -636,27 +628,11 @@ class Locd::Agent
     logger.debug "Property list written", path: plist_abs_path
     
     from_path( plist_abs_path ).tap { |agent|
-      logger.debug { ["{Agent} added", agent: agent] }
+      agent.send :log_info, "added"
     }
   end # .add
   
   
-  # @!group Removing Agents
-  # ----------------------------------------------------------------------------
-  
-  # Find an agent using a label pattern and call {#remove} on it.
-  # 
-  # @param (see .find_only!)
-  # @return (see #remove)
-  # @raise See {.find_only!} and {#remove}
-  # 
-  def self.remove *find_only_args
-    Locd::Agent.find_only!( *find_only_args ).remove
-  end # .remove
-  
-  # @!endgroup
-  
-  
   # Attributes
   # ============================================================================
   
@@ -689,9 +665,9 @@ class Locd::Agent
     
     # Sanity check...
     
-    unless plist.key? CONFIG_KEY
+    unless plist.key? Locd.config[:agent, :config_key]
       raise ArgumentError.new binding.erb <<~END
-        Not a Loc'd plist (no <%= Locd::Agent::CONFIG_KEY %> key)
+        Not a Loc'd plist (no <%= Locd.config[:agent, :config_key] %> key)
         
         path: <%= path %>
         plist:
@@ -779,7 +755,7 @@ class Locd::Agent
   
   
   def config
-    plist[CONFIG_KEY]
+    plist[Locd.config[:agent, :config_key]]
   end
   
   
@@ -822,6 +798,18 @@ class Locd::Agent
     plist['StandardErrorPath'].to_pn if plist['StandardErrorPath']
   end
   
+  
+  # Get a list of all unique log paths.
+  # 
+  # @return [Array<Pathname>]
+  # 
+  def log_paths
+    [
+      out_path,
+      err_path,
+    ].compact.uniq
+  end
+  
   # @!endgroup Instance Methods: Attribute Readers
   
   
@@ -875,15 +863,15 @@ class Locd::Agent
   # @param [Boolean] force:
   #   Force the loading of the plist. Ignore the `launchd` *Disabled* key.
   # 
-  # @param [Boolean] write:
+  # @param [Boolean] enable:
   #   Overrides the `launchd` *Disabled* key and sets it to `false`.
   # 
   # @return [self]
   # 
-  def load force: false, write: false
-    logger.debug "Loading #{ label } agent...", force: force, write: write
+  def load force: false, enable: false
+    logger.debug "Loading #{ label } agent...", force: force, enable: enable
     
-    result = Locd::Launchctl.load! path, force: force, write: write
+    result = Locd::Launchctl.load! path, force: force, write: enable
     
     message = if result.err =~ /service\ already\ loaded/
       "already loaded"
@@ -891,7 +879,7 @@ class Locd::Agent
       "LOADED"
     end
     
-    status_info message, status: status
+    log_info message, status: status
     
     self
   end
@@ -901,17 +889,17 @@ class Locd::Agent
   # 
   # This is a bit low-level; you probably want to use {#stop}.
   # 
-  # @param [Boolean] write:
+  # @param [Boolean] disable:
   #   Overrides the `launchd` *Disabled* key and sets it to `true`.
   # 
   # @return [self]
   # 
-  def unload write: false
-    logger.debug "Unloading #{ label } agent...", write: write
+  def unload disable: false
+    logger.debug "Unloading #{ label } agent...", disable: disable
     
-    result = Locd::Launchctl.unload! path, write: write
+    result = Locd::Launchctl.unload! path, write: disable
     
-    status_info "UNLOADED"
+    log_info "UNLOADED"
     
     self
   end
@@ -922,9 +910,9 @@ class Locd::Agent
   # @param (see #load)
   # @return (see #load)
   # 
-  def reload force: false, write: false
+  def reload force: false, enable: false
     unload
-    load force: force, write: write
+    load force: force, enable: enable
   end
   
   
@@ -935,23 +923,23 @@ class Locd::Agent
   # start, even if it's {#disabled?}).
   # 
   # @param [Boolean] load:
-  #   Call {#load} first, passing it `write` and `force`.
+  #   Call {#load} first, passing it `enable` and `force`.
   # 
-  # @param force (see #load)
-  # @param write (see #load)
+  # @param force  (see #load)
+  # @param enable (see #load)
   # 
   # @return [self]
   # 
-  def start load: true, force: true, write: false
+  def start load: true, force: false, enable: false
     logger.trace "Starting `#{ label }` agent...",
       load: load,
       force: force,
-      write: write
+      enable: enable
     
-    self.load( force: force, write: write ) if load
+    self.load( force: force, enable: enable ) if load
     
     Locd::Launchctl.start! label
-    status_info "STARTED"
+    log_info "STARTED"
     
     self
   end
@@ -962,19 +950,19 @@ class Locd::Agent
   # @param [Boolean] unload:
   #   Call {#unload} first, passing it `write`.
   # 
-  # @param write (see #unload)
+  # @param disable (see #unload)
   # 
   # @return [self]
   # 
-  def stop unload: true, write: false
+  def stop unload: true, disable: false
     logger.debug "Stopping `#{ label } agent...`",
       unload: unload,
-      write: write
+      disable: disable
     
     Locd::Launchctl.stop label
-    status_info "STOPPED"
+    log_info "STOPPED"
     
-    self.unload( write: write ) if unload
+    self.unload( disable: disable ) if unload
     
     self
   end
@@ -982,28 +970,44 @@ class Locd::Agent
   
   # Restart the agent ({#stop} then {#start}).
   # 
-  # @param unload (see #stop)
+  # @param [Boolean] reload:
+  #   Unload then load the agent in `launchd`.
+  #   
   # @param force  (see #start)
-  # @param write  (see #start)
+  # @param enable  (see #start)
   # 
   # @return [self]
   # 
-  def restart unload: true, force: true, write: false
-    stop unload: unload
-    start load: unload, force: force, write: write
+  def restart reload: true, force: true, enable: false
+    stop unload: reload
+    start load: reload, force: force, enable: enable
   end # #restart
   
   
   # Remove the agent by removing it's {#path} file. Will {#stop} and
   # {#unloads} the agent first.
   # 
+  # @param [Boolean] logs:
+  #   When `true` remove all logs as well.
+  # 
   # @return [self]
   # 
-  def remove
+  def remove logs: false
     stop unload: true
     
+    if logs
+      log_paths.each { |log_path|
+        if log_path.exists?
+          FileUtils.rm log_path
+          log_info "Removed log", path: log_path.to_s
+        else
+          log_info "Log path does not exist", path: log_path.to_s
+        end
+      }
+    end
+    
     FileUtils.rm path
-    status_info "REMOVED"
+    log_info "REMOVED"
     
     self
   end
@@ -1011,18 +1015,25 @@ class Locd::Agent
   # @!endgroup Instance Methods: `launchctl` Interface
   
   
+  # @!group Modifying Agents
+  # --------------------------------------------------------------------------
+  
   # Update specific values on the agent, which *may* change it's file path if
   # a different label is provided.
   # 
   # **_Does not mutate this instance! Returns a new {Locd::Agent} with the
   # updated values._**
   # 
-  # @param (see .create_plist_data)
+  # @param [Boolean] force:
+  #   Overwrite any existing agent with the same label.
+  # 
+  # @param [Hash<Symbol, Object>] **values
+  #   See {.create_plist_data}.
   # 
   # @return [Locd::Agent]
   #   A new instance with the updated values.
   # 
-  def update **values
+  def update force: false, **values
     logger.trace "Updating `#{ label }` agent", **values
     
     # Remove the `cmd_template` if it's nil of an empty array so that
@@ -1066,16 +1077,22 @@ class Locd::Agent
       # another agent
       
       if File.exists? new_plist_abs_path
-        # There's someone already there! Bail out
-        raise binding.erb <<-END
-          A different agent already exists at:
-          
-              <%= new_plist_abs_path %>
-          
-          Remove that agent first if you really want to replace it with an
-          updated version of this one.
-          
-        END
+        # There's someone already there!
+        # Bail out unless we are forcing the operation
+        if force
+          logger.info "Overwriting agent #{ new_label } with update to " \
+            "agent #{ label } (force: `true`)"
+        else
+          raise binding.erb <<-END
+            A different agent already exists at:
+            
+                <%= new_plist_abs_path %>
+            
+            Remove that agent first if you really want to replace it with an
+            updated version of this one or provide `force: true`.
+            
+          END
+        end
       end
       
       # Ok, we're in the clear (save for the obvious race condition, but,
@@ -1092,6 +1109,7 @@ class Locd::Agent
     end
   end # #update
   
+  # @!endgroup Modifying Agents
   
   
   # @!group Instance Methods: Language Integration
@@ -1167,8 +1185,20 @@ class Locd::Agent
     end
     
     
-    def status_info message, **details
-      logger.info "Agent `#{ label }` #{ message }", **details
+    # Log a message with a details payload, prefixing the agent's label.
+    # 
+    # Used to relay info to the user in the CLI.
+    # 
+    # @param [#to_s] message
+    #   Message to log.
+    # 
+    # @param [Hash<Symbol, Object>] **payload
+    #   Optional values to dump.
+    # 
+    # @return [void]
+    # 
+    def log_info message, **payload
+      logger.info "Agent `#{ label }` #{ message }", **payload
     end
     
   # end protected

data/lib/locd/agent/job.rb

@@ -113,11 +113,12 @@ class Locd::Agent::Job < Locd::Agent
     
     start_interval_data = t.match start_interval,
       t.pos_int,
-        {"StartInterval" => start_interval},
+        { "StartInterval" => start_interval },
       
       Types.start_calendar_interval,
         ->( interval ) {
-          interval.map { |key, value| [key.to_s.capitalize, value] }.to_h
+          { 'StartCalendarInterval' =>
+              interval.map { |key, value| [key.to_s.capitalize, value] }.to_h }
         },
       
       Types.start_calendar_intervals,

data/lib/locd/agent/site.rb

@@ -76,7 +76,7 @@ class Locd::Agent::Site < Locd::Agent
   #    `true` if we think this `plist` belongs to a site.
   # 
   def self.plist? plist
-    !! plist.dig( Locd::Agent::CONFIG_KEY, 'port' )
+    !! plist.dig( Locd.config[:agent, :config_key], 'port' )
   end # .plist?
   
   

data/lib/locd/agent/system.rb

@@ -55,7 +55,7 @@ module Locd::Agent::System
   # 
   def self.plist? plist
     !!(
-      plist.dig( Locd::Agent::CONFIG_KEY, 'is_system' ) \
+      plist.dig( Locd.config[:agent, :config_key], 'is_system' ) \
       && label?( plist['Label'] )
     )
   end # .plist?

data/lib/locd/cli/command/agent.rb

@@ -117,18 +117,36 @@ class Locd::CLI::Command::Agent < Locd::CLI::Command::Base
   # Options when provided a `PATTERN` argument used to find agents by label.
   # 
 
-  shared_option :exact,
+  shared_option :full,
     groups: :pattern,
-    desc: "Force PATTERN to match entire label string",
-    aliases: '-x',
+    desc: "Require label PATTERN to match entire string",
+    aliases: '-u',
+    type: :boolean
+    
+  shared_option :ignore_case,
+    groups: :pattern,
+    desc: "Make label PATTERN case-insensitive",
+    aliases: '-i',
     type: :boolean
   
   shared_option :recursive,
     groups: :pattern,
-    desc: "Workdir patterns match all subdirs too",
+    desc: "Make workdir PATTERN match all subdirs too",
     aliases: '-r',
     type: :boolean
   
+  # NOTE  We don't expose the workdir pattern's `:cwd` option...
+  #       If you want to match a directory from the CLI, just provide that
+  #       directory... no reason to specify the `:cwd` in an option then
+  #       provide a relative PATTERN
+  # 
+  
+  # `:multi` Group
+  # ----------------------------------------------------------------------------
+  # 
+  # For commands that can match multiple agents.
+  # 
+  
   shared_option :all,
     groups: :multi,
     desc: "Apply to ALL agents that PATTERN matches",
@@ -161,11 +179,25 @@ class Locd::CLI::Command::Agent < Locd::CLI::Command::Base
     aliases: ['--log'],
     type: :string
   
+  shared_option :keep_alive,
+    groups: :write,
+    desc: "Try to keep the agent running",
+    type: :boolean,
+    default: false
+  
+  shared_option :run_at_load,
+    groups: :write,
+    desc: "Start the agent when loading it",
+    type: :boolean,
+    default: false
+
+  
+  # `:add` Group
+  # ----------------------------------------------------------------------------
   
   shared_option :force,
     groups: :add,
     desc: "Overwrite any existing agent",
-    aliases: '-f',
     type: :boolean,
     default: false
   
@@ -177,12 +209,6 @@ class Locd::CLI::Command::Agent < Locd::CLI::Command::Base
     default: true
   
   
-  shared_option :unload,
-    groups: :start,
-    desc: "Unload the agent from `launchd` after stopping",
-    type: :boolean,
-    default: true
-  
   # Commands
   # ============================================================================
   
@@ -191,9 +217,12 @@ class Locd::CLI::Command::Agent < Locd::CLI::Command::Base
   
   desc              "ls [PATTERN]",
                     "List agents"
+  
   map               list: :ls
+  
   include_options   :long,
                     groups: :pattern
+  
   def ls            pattern = nil
     results = if pattern.nil?
       agent_class.all
@@ -205,20 +234,74 @@ class Locd::CLI::Command::Agent < Locd::CLI::Command::Base
   end
   
   
-  # Write Commands
+  desc              "plist PATTERN",
+                    "Print an agent's launchd property list"
+  
+  include_options   groups: :pattern
+  
+  def plist         pattern
+    agent = find_only! pattern
+    
+    if options[:json] || options[:yaml]
+      respond agent.plist
+    else
+      respond agent.path.read
+    end
+  end
+  
+  
+  desc              'status PATTERN',
+                    "Print agent status"
+  
+  include_options   groups: :pattern
+  
+  def status        pattern
+    agent = find_only! pattern
+    respond \
+      label:  agent.label,
+      port:   agent.port,
+      status: agent.status
+  end
+  
+  
+  # Commands for Manipulating Agent Definitions
   # ----------------------------------------------------------------------------
   
   desc              "add CMD_TEMPLATE...",
-                    "Add agents that runs a command in the current directory"
+                    "Add an agent that runs a command in the current directory"
+   
   include_options   groups: [:write, :add, :respond_with_agents]
-  def add           *cmd_template
-    agent = agent_class.add \
+  
+  def add           *cmd_template, **kwds
+    logger.trace __method__.to_s,
       cmd_template: cmd_template,
-      **option_kwds( groups: :write )
+      kwds: kwds,
+      options: options
     
-    logger.info "`#{ agent.label }` agent created."
+    # Merge all the keywords together into the format needed to call
+    # {Locd::Agent.add}
+    kwds.merge! **option_kwds( :force, groups: [:write] ),
+                cmd_template: cmd_template
     
-    agent.load if options[:load]
+    # Check args
+    
+    # `:cmd_template` can not be empty at this point
+    if kwds[:cmd_template].empty? || kwds[:cmd_template].all?( &:empty? )
+      raise Thor::RequiredArgumentMissingError,
+        "CMD_TEMPLATE argument is required to add an agent"
+    end
+    
+    # Need a `:label` too
+    unless t.non_empty_str === kwds[:label]
+      raise Thor::RequiredArgumentMissingError,
+        "--label=LABEL option is required to add an agent"
+    end
+    
+    # Do the add
+    agent = agent_class.add **kwds
+    
+    # Reload (unless we were told not to... usually you want to reload)
+    agent.reload if options[:load]
     
     respond agent
   end
@@ -226,7 +309,9 @@ class Locd::CLI::Command::Agent < Locd::CLI::Command::Base
   
   desc              "update PATTERN [OPTIONS] [-- CMD_TEMPLATE...]",
                     "Update an existing agent"
+  
   include_options   groups: [:pattern, :write, :respond_with_agents]
+  
   def update        pattern, *cmd_template
     agent = find_only! pattern
     
@@ -240,71 +325,193 @@ class Locd::CLI::Command::Agent < Locd::CLI::Command::Base
   end
   
   
-  desc              "open PATTERN",
-                    "Open an agent's URL in the browser"
-  include_options   groups: [:pattern, :multi]
-  def open          pattern
-    find_multi!( pattern ).each do |agent|
-      Cmds! "open %s", agent.url
-      logger.info "Opened agent `#{ agent.label }` at #{ agent.url }"
-    end
-  end
-  
-  
   desc              "rm PATTERN",
                     "Remove (uninstall, delete) a agent"
+  
   map               remove: :rm
+  
   include_options   groups: [:pattern, :multi]
+  
+  option            :logs,
+                    desc: "Remove logs too",
+                    type: :boolean,
+                    default: false
+  
   def rm            pattern
-    agent_class.remove pattern, **option_kwds( :exact )
+    kwds = option_kwds :logs
+    find_multi!( pattern ).each { |agent| agent.remove **kwds }
   end
   
   
-  desc              "plist PATTERN",
-                    "Show an agent's launchd property list"
-  include_options   groups: :pattern
-  def plist         pattern
-    # TODO  Why doesn't this use {#find_only!}?
-    agent = agent_class.find_only! pattern, **option_kwds( :exact )
-    
-    if options[:json] || options[:yaml]
-      respond agent.plist
-    else
-      respond agent.path.read
-    end
-  end
+  # Commands for Manipulating Agent State
+  # --------------------------------------------------------------------------
   
-    
   desc              "start PATTERN",
                     "Start an agent"
+  
   include_options   groups: :pattern
-  option            :write,
+  
+  option            :load,
+                    desc: "Load the agent before starting",
+                    type: :boolean,
+                    default: true
+  
+  option            :force,
+                    desc: "Force loading of agent even if it's disabled",
+                    type: :boolean,
+                    default: false
+  
+  option            :enable,
                     desc: "Set `launchd` *Disabled* key to `false`",
-                    type: :boolean
+                    type: :boolean,
+                    default: false
+  
   def start         pattern
-    find_only!( pattern ).start
+    find_only!( pattern ).start **option_kwds( :load, :force, :enable )
   end
   
   
   desc              "stop PATTERN",
                     "Stop an agent"
+  
   include_options   groups: [:pattern, :stop]
-  option            :write,
+  
+  option            :unload,
+                    desc: "Unload the agent from `launchd` after stopping",
+                    type: :boolean,
+                    default: true
+  
+  option            :disable,
                     desc: "Set `launchd` *Disabled* key to `true`",
-                    type: :boolean
+                    type: :boolean,
+                    default: false
+  
   def stop          pattern
-    find_only!( pattern ).stop **option_kwds( :unload )
+    find_only!( pattern ).stop **option_kwds( :unload, :disable )
   end
   
   
   desc              "restart PATTERN",
                     "Restart an agent"
+  
   include_options   groups: [:pattern, :stop]
-  option            :write,
+  
+  option            :reload,
+                    desc: "Unload and reload the agent in `launchd`",
+                    type: :boolean,
+                    default: true
+  
+  option            :force,
+                    desc: "Force loading of agent even if it's disabled",
+                    type: :boolean,
+                    default: false
+  
+  option            :enable,
                     desc: "Set `launchd` *Disabled* key to `false`",
-                    type: :boolean
+                    type: :boolean,
+                    default: false
+  
   def restart       pattern
-    find_only!( pattern ).restart
+    find_only!( pattern ).restart **option_kwds( :reload, :force, :enable )
   end
   
+  
+  # Assorted Other Commands
+  # ----------------------------------------------------------------------------
+  
+  desc              "open PATTERN",
+                    "Open an agent's URL in the browser"
+  
+  include_options   groups: [:pattern, :multi]
+  
+  def open          pattern
+    find_multi!( pattern ).each do |agent|
+      Cmds! "open %s", agent.url
+      logger.info "Opened agent `#{ agent.label }` at #{ agent.url }"
+    end
+  end
+  
+  
+  desc              'truncate_logs PATTERN',
+                    "Truncate agent log file(s)."
+  
+  include_options   groups: [:pattern, :multi]
+  
+  option            :restart,
+                    desc: "Restart the agent after truncation",
+                    type: :boolean,
+                    default: true
+  
+  def truncate_logs pattern
+    find_multi!( pattern ).each do |agent|
+      log_paths = [agent.out_path, agent.err_path].compact.uniq
+      
+      unless log_paths.empty?
+        restart = options[:restart] && agent.running?
+        
+        agent.stop if restart
+        
+        log_paths.each do |log_path|
+          begin
+            log_path.open( 'w' ) { |f| f.truncate 0 }
+          rescue Exception => error
+            logger.error "Failed to truncate #{ log_path }", error
+          else
+            logger.info "Truncated",
+              'file' => log_path.to_s,
+              'agent.label' => agent.label
+          end
+        end # each log_path
+        
+        agent.start if restart
+      end # unless log_paths.empty?
+    end # each agent
+  end # #truncate_logs
+  
+  
+  desc              'tail [OPTIONS] PATTERN [-- TAIL_OPTIONS]',
+                    "Tail agent logs"
+  
+  include_options   groups: :pattern
+  
+  option            :stream,
+                    desc: "Stream to tail. May omit if uses single log file.",
+                    aliases: ['-s'],
+                    type: :string,
+                    enum: ['out', 'err']
+  
+  def tail          pattern, *tail_options
+    agent = find_only! pattern
+    
+    path = case options[:stream]
+    when nil
+      paths = agent.log_paths
+      
+      unless paths.length == 1
+        raise Thor::RequiredArgumentMissingError.new binding.erb <<~END
+          Agent `<%= agent.label %>` has multiple log files.
+          
+          out: <%= agent.out_path.to_s %>
+          err: <%= agent.err_path.to_s %>
+          
+          Must specify one via the `--stream` option.
+          
+        END
+      end
+      
+      paths[0]
+      
+    when 'out'
+      agent.out_path
+      
+    when 'err'
+      agent.err_path
+      
+    else
+      raise "WTF"
+    end
+    
+    exec "tail", *tail_options, path.to_s
+  end # #tail
+  
 end # class Locd::CLI::Command::Agent