Cannot use CLI as library: Run() requires internal SpinnerPrinter

[isbecker]

What happened?

PR #10 introduced a breaking change that makes public APIs unusable for external consumers.

The SpinnerPrinter parameter was added to public Run() methods across multiple commands (render, validate, etc.), but the SpinnerPrinter interface is defined in github.com/crossplane/cli/v2/internal/terminal, which Go's module system prevents external code from importing.

This creates an impossible situation:

• The Run() methods are exported (titlecase) and intended to be public APIs
• External code cannot implement or obtain a SpinnerPrinter because it's in an internal/ package
• Therefore these public APIs are now completely unusable by external consumers

Example of broken API:

// github.com/crossplane/cli/v2/cmd/crossplane/render/xr
func (c *Cmd) Run(k *kong.Context, log logging.Logger, sp terminal.SpinnerPrinter) error

External code cannot:

• Import github.com/crossplane/cli/v2/internal/terminal (Go won't allow it)
• Implement the SpinnerPrinter interface (can't reference the type)
• Call terminal.NewSpinnerPrinter() (function is in internal package)

How can we reproduce it?

Try to use the CLI as a library from external Go code (commit bc59509 or later):

package main

import (
  "github.com/crossplane/cli/v2/cmd/crossplane/render/xr"
  // Cannot import: github.com/crossplane/cli/v2/internal/terminal
)

func main() {
  cmd := &xr.Cmd{...}
  // Cannot call: cmd.Run(ctx, logger, ???)
  // No way to obtain or create a SpinnerPrinter
}

Compile error:
use of internal package github.com/crossplane/cli/v2/internal/terminal not allowed

Suggested fixes:

1. Move SpinnerPrinter to a public package (e.g., github.com/crossplane/cli/v2/terminal)
2. Provide a public constructor for a no-op/disabled spinner (e.g., terminal.NewNoOpSpinner())
3. Make the parameter optional via an options pattern or accept interface{} that can be nil
4. Accept io.Writer instead and construct the spinner internally based on whether it's a TTY

What environment did it happen in?

• Crossplane CLI version: v2.0.0-20260520190424-bc595092600d (commit from PR Introduce an initial set of DevEx features #10)
• Platform: linux/amd64
• Go version: 1.26.0

[adamwg]

@isbecker Thanks for reporting. Could you provide some details on what your use-case is for calling the command code externally? In general, I think it's an anti-pattern to consume code from cmd/, although this is a common pattern with the CLI since there's lots of useful stuff there. We have talked about doing some refactoring to expose useful code from the CLI for external consumers in a pkg/ directory so that cmd/ stays more focused on CLI details and doesn't need to be imported. If we're able to serve your use-case by factoring reusable code out of cmd/ and into pkg/, that would be my preference.

[isbecker]

@adamwg Hi thanks for responding so quickly.

What we're doing is using things like the render command to process compositions. We have a go tool which bundles that command and some other packages from the go ecosystem that we use for our composition devex.

For render in particular, it does a ton of work in Run() which would be difficult or foolish to re-implement. It is acknowledged that the rendering is doing quite a lot of work, i.e. this comment on that method:

func (c *Cmd) Run(...) error { //nolint:gocognit // Orchestration is inherently complex. <-- yes, it is

I would be happy if the core logic of render could be factored out in pkg/, that would be preferable. Others that I might be interested in, in no particular order:

• validate
• trace
• xpkg