github.com/jfrog/jfrog-cli-core/v2@v2.52.0/plugins/README.md (about)

     1  # Guidelines for Creating JFrog CLI Plugins
     2  
     3  This comprehensive guide equips you with essential tools to embark on implementing a JFrog CLI plugin project or a related feature.
     4  
     5  ## Table of Contents
     6  * [Implementing a JFrog CLI plugin](#implementing-a-jfrog-cli-plugin)
     7  * [Adding a Command](#adding-a-command)
     8  * [Utilities](#utilities)
     9  * [Examples](#examples)
    10  
    11  ## Implementing a JFrog CLI plugin
    12  
    13  Creating a plugin requires implementing a project that adheres to the structures outlined in the plugin [components](../plugins/components/structure.go). Below is a sample illustrating how to utilize these structures within the main package:
    14  
    15  ```go
    16  package main
    17  
    18  import (
    19  	"github.com/jfrog/jfrog-cli-core/v2/plugins"
    20      "github.com/jfrog/jfrog-cli-core/v2/plugins/components"
    21  )
    22  
    23  func main() {
    24  	// Run this plugin CLI as a stand-alone.
    25  	plugins.PluginMain(GetApp())
    26  }
    27  
    28  func GetApp() components.App {
    29  	app := components.CreateApp(
    30          // Plugin namespace prefix (command usage: app <cmd-name>)
    31  		"app",
    32          // Plugin version vX.X.X
    33  		"v1.0.0",
    34          // Plugin description for help usage
    35  		"description",
    36          // Plugin commands
    37  		GetCommands(),
    38  	)
    39  	return app
    40  }
    41  
    42  func GetCommands() []components.Command {
    43      return []components.Command{
    44  		{
    45  			Name:        "greet",
    46  			Description: "Greet the user with log",
    47  			Action:      GreetCmd,
    48  		},
    49      }
    50  }
    51  ```
    52  
    53  The plugin needs to specify a list of all commands under their respective namespaces. Each command is defined using the `Command` structure.
    54  
    55  ## Adding a Command
    56  
    57  To add a command you need to insert an entry to the commands list. the entry is an instance of the `Command` structure that defines an `Action` to execute when triggered, as mentioned at this example:
    58  
    59  ```go
    60  cmd := components.Command{
    61  	Name:        "greet",
    62  	Aliases:	 []string{"g"},
    63  	Description: "Greet the user with log",
    64  	Action:      GreetCmd,
    65  },
    66  
    67  // Parse the command context and execute the command action.
    68  func GreetCmd(c *components.Context) (err error) {
    69  	log.Info("Hello World")
    70  	return
    71  }
    72  ```
    73  
    74  ### Define Arguments
    75  
    76  For defining arguments within a command, follow this approach:
    77  
    78  ```go
    79  cmd := components.Command{
    80  	Name:        "greet",
    81  	// The expected order of the arguments entered by the user is the same order that they are defined at this list.
    82  	Arguments: []components.Argument{
    83  		{
    84  			Name: "name",
    85  			Description: "Add the given name to the greeting log",
    86  		},
    87  	}
    88  	Action:      GreetCmd,
    89  }
    90  
    91  // Parse the command context and execute the command action.
    92  func GreetCmd(c *components.Context) (err error) {
    93  	who := "Frog"
    94  	if len(c.Arguments) == 1 {
    95  		who = c.Arguments[0]
    96  	} else if len(c.Arguments) > 1 {
    97  		return pluginsCommon.WrongNumberOfArgumentsHandler(c)
    98  	}
    99  	log.Info(fmt.Sprintf("Hello %s", who))
   100  	return
   101  }
   102  ```
   103  
   104  ### Define flags
   105  
   106  For defining flags within a command, refer to this example:
   107  
   108  ```go
   109  cmd := components.Command{
   110  	Name:        "greet",
   111  	Flags:	 	 []components.Flag{
   112  		components.NewBoolFlag(
   113  			"pretty", 
   114  			"Set to false to log simple greeting without decorations.", 
   115  			components.WithBoolDefaultValue(true),
   116  		),
   117  	},
   118  	Action:      GreetCmd,
   119  }
   120  
   121  // Parse the command context and execute the command action.
   122  func GreetCmd(c *components.Context) (err error) {
   123  	toLog := "Hello World"
   124  	if c.IsFlagSet("pretty") && c.GetBoolFlagValue("pretty") {
   125  		toLog = 🐸 + " " + toLog + "! " + 🌐
   126  	}
   127  	log.Info(toLog)
   128  	return
   129  }
   130  ```
   131  
   132  ## Utilities
   133  
   134  Before implementing generic logic, ensure it hasn't been implemented yet.
   135  
   136  * Find plugin and `Context` common utilities at [plugins/](../plugins/)
   137  
   138  * Discover CLI common commands, utilities and global constants at [common/](../common/)
   139  
   140  * Find general utilities at [utils](../utils/)
   141  
   142  ## Examples
   143  
   144  Explore JFrog CLI Plugin examples in these repositories:
   145  
   146  * [Jfrog CLI Plugins](https://github.com/jfrog/jfrog-cli-plugins)
   147  * [JFrog Security](https://github.com/jfrog/jfrog-cli-security)