docs: def run(*args, **kwargs):
      '''
      Execute a puppet run and return a dict with the stderr, stdout,
      return code, etc. The first positional argument given is checked as a
      subcommand. Following positional arguments should be ordered with arguments
      required by the subcommand first, followed by non-keyword arguments.
      Tags are specified by a tag keyword and comma separated list of values. --
      http://docs.puppetlabs.com/puppet/latest/reference/lang_tags.html
  
      CLI Examples:
  
      .. code-block:: bash
  
          salt '*' puppet.run
          salt '*' puppet.run tags=basefiles::edit,apache::server
          salt '*' puppet.run agent onetime no-daemonize no-usecacheonfailure no-splay ignorecache
          salt '*' puppet.run debug
          salt '*' puppet.run apply /a/b/manifest.pp modulepath=/a/b/modules tags=basefiles::edit,apache::server
      '''
      puppet = _Puppet()
  
      # new args tuple to filter out agent/apply for _Puppet.arguments()
      buildargs = ()
      for arg in range(len(args)):
          # based on puppet documentation action must come first. making the same
          # assertion. need to ensure the list of supported cmds here matches
          # those defined in _Puppet.arguments()
          if args[arg] in ['agent', 'apply']:
              puppet.subcmd = args[arg]
          else:
              buildargs += (args[arg],)
      # args will exist as an empty list even if none have been provided
      puppet.arguments(buildargs)
  
      puppet.kwargs.update(salt.utils.args.clean_kwargs(**kwargs))
  
      ret = __salt__['cmd.run_all'](repr(puppet), python_shell=True)
      return ret