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)