#2090 - Introduce extensibility to Chainloop CLI

[gr0]

This is an experimental approach to #2090 - the part of the whole solution providing the framework part.

An example implementation could look more or less like this:

main.go:

package main

import (
	"log"
	"os"

	"github.com/chainloop-dev/chainloop/pkg/plugins"
	"github.com/gr0/example-plugin/pkg"
	"github.com/hashicorp/go-plugin"
)

func main() {
	log.SetOutput(os.Stderr)
	log.Println("Plugin starting...")

	// Create the plugin instance
	pluginInstance := &pkg.ExamplePlugin{}
	log.Println("Plugin instance created")

	plugin.Serve(&plugin.ServeConfig{
		HandshakeConfig: plugins.Handshake,
		Plugins: map[string]plugin.Plugin{
			"chainloop": &plugins.ChainloopCliPlugin{Impl: pluginInstance},
		},
	})
}

And the pkg/plugin.go:

package pkg

import (
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"time"

	"github.com/chainloop-dev/chainloop/pkg/plugins"
)

type ExamplePlugin struct{}

func (p *ExamplePlugin) Exec(ctx context.Context, command string, arguments map[string]interface{}) (plugins.ExecResult, error) {
	switch command {
	case "example-hello":
		return p.execHello(ctx, arguments)
	default:
		return &Result{
			Error:    fmt.Sprintf("Unknown command: %s", command),
			ExitCode: 1,
		}, nil
	}
}

func (p *ExamplePlugin) execHello(ctx context.Context, arguments map[string]interface{}) (plugins.ExecResult, error) {
	return &Result{
		Output: "Hello, World!",
	}, nil
}

func (p *ExamplePlugin) GetMetadata(ctx context.Context) (plugins.PluginMetadata, error) {
	return plugins.PluginMetadata{
		Name:        "example",
		Version:     "1.0.0",
		Description: "Example plugin",
		Commands: []plugins.CommandInfo{
			{
				Name:        "example-hello",
				Description: "Greet with hello",
				Usage:       "chainloop example-hello",
				Flags:       []plugins.FlagInfo{},
			},
		},
	}, nil
}

type Result struct {
	Output   string
	Error    string
	ExitCode int
	Data     map[string]interface{}
}

func (r *Result) GetOutput() string {
	return r.Output
}

func (r *Result) GetError() string {
	return r.Error
}

func (r *Result) GetExitCode() int {
	return r.ExitCode
}

func (r *Result) GetData() map[string]interface{} {
	return r.Data
}

[jiparis]

I'm wondering if we can use a Cobra struct here. That way, there's no need to parse this structure in createPluginCommand, just use them natively.

[jiparis]

Thanks @gr0 . This is looking great. I've left a couple of comments.

[jiparis]

There are some variables in root.go that get their values from some persistent flags. They should be passed as well. For example apiToken, flagDebug, flagOutputFormat, cpPanelAPI, etc.
Not sure what's the best pattern, but plugins might need to use them.

[migmartri]

btw, in the main CLI we use something like configPath := filepath.Join(xdg.ConfigHome, appName), you can do the same or extract that to a function

[migmartri]

there is a discover function in the library itself that we could use https://pkg.go.dev/github.com/hashicorp/[email protected]#Discover

This is how we use it in the controlplane, it might help

chainloop/app/controlplane/plugins/plugins.go

Line 158 in 48bffa8

return nil, fmt.Errorf("failed to discover plugins: %w", err)

[gr0]

Hmm... indeed, I'll try that out.

[migmartri]

for consistency with integrations I'd use describe and not to use arguments but instead --name flag

chainloop integration available describe --name guac

I am not in love with using always flags instead of positional arguments but for the sake of conventions I'd use the same, what do you think? cc/ @jiparis

[jiparis]

I have no preference to be honest, but if it's for consistency, I agree.

[gr0]

Good point, will change.

[migmartri]

does it need to be executable? Is this a requirement of the plugin library, I wasn't aware of it.

How did you build the test plugin? I did

go build -o ~/.config/chainloop/plugins/test-plugin main.go

in the test plugin you pasted and it doesn't load it.

 go run main.go plugin ls
WRN API contacted in insecure mode
No plugins installed

if I make it executable I get this error

go run main.go plugin ls
2025-06-05T16:15:53.855+0200 [DEBUG] plugin: starting plugin: path=/Users/miguelmartinez/.config/chainloop/plugins/test-plugin args=["/Users/miguelmartinez/.config/chainloop/plugins/test-plugin"]
2025-06-05T16:15:53.856+0200 [WARN]  plugin: plugin failed to exit gracefully
WRN API contacted in insecure mode
No plugins installed

[gr0]

In my case I was just building an example with:

go build -o plugin-one ./cmd/

Let me create an example repository with a plugin, so I can show the whole implementation. I'll prepare something for tomorrow.

[gr0]

Btw - can you try running the compiled Chainloop binary and listing the plugins - I was testing using the locally compiled binary using goreleased. I'm wondering if that can be the case, I'll try running in a similar way you did.

[migmartri]

for some reason I can see the debug level logs? Do you know why? By default we are at info level?

2025-06-05T16:15:53.855+0200 [DEBUG] plugin: starting plugin: path=/Users/miguelmartinez/.config/chainloop/plugins/test-plugin args=["/Users/miguelmartinez/.config/chainloop/plugins/test-plugin"]

[jiparis]

Could it be that the plugins are being loaded before initializing the logger, which happens in root's PersistentPreRunE?

[gr0]

Yes, I think there are some issues with logger initialization - I'll handle that once the "juicy" parts are stabilized :)

[gr0]

I found the problem - I will fix it.

[gr0]

Just as an update - the issue right now is that by default, the logger in the go-plugin lib is created with DEBUG level. It can be changed, but I need to slightly redo how the plugin commands are executed, because in the current form it will be run with the not yet initialized logger, which means that the level will be set to DEBUG result in exactly the same behavior. I will change the implementation and move to actions.