feat(extension): implicit plugin mechanism via circleci-<name> PATH lookup

Unknown top-level commands transparently exec a matching circleci-<name>
binary from PATH, following git's plugin convention. The extension
receives CIRCLE_TOKEN, CIRCLE_URL, and best-effort project metadata
(VCS type, org, repo) via environment variables so it can call the
CircleCI API without reimplementing auth.

Only top-level unknown commands are intercepted — unknown subcommands
within a group (e.g. "circleci pipeline foo") still produce the normal
cobra error.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: webster

internal/extension/extension.go

@@ -0,0 +1,131 @@
+// Copyright (c) 2026 Circle Internet Services, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+//
+// SPDX-License-Identifier: MIT
+
+// Package extension implements the circleci plugin mechanism.
+//
+// Any executable named "circleci-<name>" found in PATH is treated as an
+// extension and can be invoked transparently as "circleci <name>". The
+// extension receives CIRCLE_TOKEN, CIRCLE_URL, and best-effort project
+// metadata via environment variables so it can call the CircleCI API without
+// reimplementing authentication.
+package extension
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+
+	"github.com/CircleCI-Public/circleci-cli-v2/internal/config"
+	"github.com/CircleCI-Public/circleci-cli-v2/internal/gitremote"
+)
+
+// ErrNotFound is returned when no circleci-<name> binary exists in PATH.
+type ErrNotFound struct {
+	Name string
+}
+
+func (e *ErrNotFound) Error() string {
+	return fmt.Sprintf("unknown command %q — and no extension %q found in PATH", e.Name, "circleci-"+e.Name)
+}
+
+// Run looks up circleci-<name> in PATH and execs it with args, injecting
+// CircleCI environment variables. configPath is the --config flag value
+// (empty means use the default XDG path). The current process is replaced
+// by the extension via syscall exec on Unix; on Windows the extension is
+// run as a child process and its exit code is propagated.
+//
+// If no matching binary is found, ErrNotFound is returned and the caller
+// should show the original "unknown command" error instead.
+func Run(ctx context.Context, name string, args []string, configPath string) error {
+	binary := "circleci-" + name
+	path, err := exec.LookPath(binary)
+	if err != nil {
+		return &ErrNotFound{Name: name}
+	}
+
+	env := buildEnv(ctx, configPath)
+
+	cmd := exec.CommandContext(ctx, path, args...) //#nosec:G204 // path comes from LookPath, args are user-supplied CLI args for the extension
+	cmd.Stdin = os.Stdin
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	cmd.Env = env
+
+	if err := cmd.Run(); err != nil {
+		if cmd.ProcessState != nil {
+			// Exit with the extension's exit code, not our own error message.
+			os.Exit(cmd.ProcessState.ExitCode())
+		}
+		return fmt.Errorf("extension %q failed: %w", binary, err)
+	}
+	return nil
+}
+
+// buildEnv constructs the environment for the extension process. It starts
+// from the current process environment and overlays CIRCLE_* variables so
+// extensions can call the CircleCI API without reimplementing auth.
+func buildEnv(ctx context.Context, configPath string) []string {
+	env := os.Environ()
+
+	cfg, err := config.LoadFrom(ctx, configPath, false)
+	if err != nil {
+		cfg = &config.Config{}
+	}
+
+	overlays := map[string]string{
+		"CIRCLE_TOKEN": cfg.EffectiveToken(),
+		"CIRCLE_URL":   cfg.EffectiveHost(),
+	}
+
+	// Best-effort: inject project metadata from git remote. Failures are
+	// silently ignored — the extension is responsible for handling missing vars.
+	if info, err := gitremote.Detect(); err == nil {
+		parts := strings.SplitN(info.Slug, "/", 3)
+		if len(parts) == 3 {
+			overlays["CIRCLE_VCS_TYPE"] = vcsLong(parts[0])
+			overlays["CIRCLE_PROJECT_USERNAME"] = parts[1]
+			overlays["CIRCLE_PROJECT_REPONAME"] = parts[2]
+		}
+	}
+
+	for k, v := range overlays {
+		if v != "" {
+			env = append(env, k+"="+v)
+		}
+	}
+	return env
+}
+
+func vcsLong(short string) string {
+	switch short {
+	case "gh":
+		return "github"
+	case "bb":
+		return "bitbucket"
+	case "gl":
+		return "gitlab"
+	default:
+		return short
+	}
+}

main.go

@@ -28,10 +28,12 @@ import (
 	"fmt"
 	"os"
 	"os/signal"
+	"strings"
 	"syscall"
 
 	"github.com/CircleCI-Public/circleci-cli-v2/internal/cmd/root"
 	clierrors "github.com/CircleCI-Public/circleci-cli-v2/internal/errors"
+	"github.com/CircleCI-Public/circleci-cli-v2/internal/extension"
 )
 
 var version = "dev"
@@ -51,6 +53,23 @@ func run() int {
 	rootCmd := root.NewRootCmd(version)
 	rootCmd.SetContext(ctx)
 	if err := rootCmd.Execute(); err != nil {
+		// Before reporting "unknown command", try the implicit extension mechanism:
+		// any executable named "circleci-<name>" in PATH is a valid extension.
+		// Only intercept top-level unknown commands (error ends with `for "circleci"`).
+		if name, ok := rootUnknownCommand(err); ok {
+			configPath, _ := rootCmd.Flags().GetString("config")
+			extArgs := extensionArgs(name)
+			extErr := extension.Run(ctx, name, extArgs, configPath)
+			if extErr == nil {
+				return clierrors.ExitSuccess
+			}
+			// Extension not found — fall through and show the original cobra error.
+			if !errors.As(extErr, new(*extension.ErrNotFound)) {
+				_, _ = fmt.Fprintln(os.Stderr, extErr)
+				return clierrors.ExitGeneralError
+			}
+		}
+
 		if cliErr, ok := errors.AsType[*clierrors.CLIError](err); ok {
 			if jsonFlagPresent() {
 				_, _ = fmt.Fprint(os.Stderr, cliErr.FormatJSON())
@@ -65,6 +84,39 @@ func run() int {
 	return clierrors.ExitSuccess
 }
 
+// rootUnknownCommand reports whether err is Cobra's "unknown command" error
+// for the root command specifically (not a nested group). Returns the command
+// name that was not found.
+func rootUnknownCommand(err error) (string, bool) {
+	msg := err.Error()
+	// Cobra formats this as: unknown command "foo" for "circleci"
+	const prefix = `unknown command "`
+	if !strings.HasPrefix(msg, prefix) {
+		return "", false
+	}
+	// Must be for the root, not a subgroup like "circleci pipeline".
+	if !strings.HasSuffix(msg, `for "circleci"`) {
+		return "", false
+	}
+	name, _, ok := strings.Cut(msg[len(prefix):], `"`)
+	if !ok {
+		return "", false
+	}
+	return name, true
+}
+
+// extensionArgs returns the arguments to pass to the extension binary.
+// It scans os.Args for the first non-flag positional argument matching name
+// and returns everything after it.
+func extensionArgs(name string) []string {
+	for i, arg := range os.Args[1:] {
+		if !strings.HasPrefix(arg, "-") && arg == name {
+			return os.Args[i+2:]
+		}
+	}
+	return nil
+}
+
 // jsonFlagPresent reports whether --json appears anywhere in the raw argument
 // list. This is intentionally a simple scan rather than full flag parsing —
 // we only need it to format errors before Cobra has had a chance to run.