cmd

Documentation

Overview

Package cmd provides CLI command implementations with user-friendly error handling.

Index

• Variables
• func Execute(ctx context.Context) error
• func ExecuteCommand(cmd *cobra.Command, f *Factory) error
• func FormatError(err error) error
• func NewAuthCmd(f *Factory) *cobra.Command
• func NewCompletionCmd() *cobra.Command
• func NewConfigCmd(f *Factory) *cobra.Command
• func NewHelpJSONCmd() *cobra.Command
• func NewInsightsCmd(f *Factory) *cobra.Command
• func NewIntentsCmd() *cobra.Command
• func NewListCommand[T any](cfg ListConfig[T], getClient func(context.Context) (*api.Client, error)) *cobra.Command
• func NewLocationsCmd(f *Factory) *cobra.Command
• func NewOEmbedCmd(f *Factory) *cobra.Command
• func NewPostsCmd(f *Factory) *cobra.Command
• func NewRateLimitCmd(f *Factory) *cobra.Command
• func NewRepliesCmd(f *Factory) *cobra.Command
• func NewRootCmd(f *Factory) *cobra.Command
• func NewSearchCmd(f *Factory) *cobra.Command
• func NewUsersCmd(f *Factory) *cobra.Command
• func NewUsersMeCmd(f *Factory) *cobra.Command
• func NewVersionCmd() *cobra.Command
• func NewWebhooksCmd(f *Factory) *cobra.Command
• func ValidateHTTPSURL(rawURL, fieldName string) error
• func WrapError(context string, err error) error
• func WriteErrorTo(ctx context.Context, w io.Writer, err error)
• type Factory
  • func NewFactory(ctx context.Context, opts FactoryOptions) (*Factory, error)
  • func (f *Factory) ActiveCredentials(_ context.Context) (*secrets.Credentials, error)
  • func (f *Factory) Client(ctx context.Context) (*api.Client, error)
  • func (f *Factory) Confirm(ctx context.Context, prompt string) bool
  • func (f *Factory) UI(ctx context.Context) *ui.Printer
• type FactoryOptions
• type ListConfig
• type ListResult
• type RootOptions
• type UserFriendlyError
  • func (e *UserFriendlyError) Error() string
  • func (e *UserFriendlyError) Unwrap() error

Variables

var (
	// Version information (set via ldflags)
	Version   = "dev"
	Commit    = "none"
	BuildDate = "unknown"
)

Functions

func Execute

func Execute(ctx context.Context) error

Execute runs the CLI with a new factory and root command.

func ExecuteCommand

func ExecuteCommand(cmd *cobra.Command, f *Factory) error

ExecuteCommand runs a prepared command and handles formatted errors.

func FormatError

func FormatError(err error) error

FormatError converts API errors and common errors into user-friendly messages with actionable suggestions. This should be called on errors before returning them to the user.

func NewAuthCmd

func NewAuthCmd(f *Factory) *cobra.Command

NewAuthCmd builds the auth command group.

func NewCompletionCmd

func NewCompletionCmd() *cobra.Command

func NewConfigCmd

func NewConfigCmd(f *Factory) *cobra.Command

NewConfigCmd builds the config command group.

func NewHelpJSONCmd

func NewHelpJSONCmd() *cobra.Command

func NewInsightsCmd

func NewInsightsCmd(f *Factory) *cobra.Command

NewInsightsCmd builds the insights command group.

func NewIntentsCmd

func NewIntentsCmd() *cobra.Command

NewIntentsCmd builds the web intents command group.

func NewListCommand

func NewListCommand[T any](cfg ListConfig[T], getClient func(context.Context) (*api.Client, error)) *cobra.Command

NewListCommand creates a new list command using the provided configuration

func NewLocationsCmd

func NewLocationsCmd(f *Factory) *cobra.Command

NewLocationsCmd builds the locations command group.

func NewOEmbedCmd

func NewOEmbedCmd(f *Factory) *cobra.Command

NewOEmbedCmd builds the oembed command.

func NewPostsCmd

func NewPostsCmd(f *Factory) *cobra.Command

NewPostsCmd builds the posts command group.

func NewRateLimitCmd

func NewRateLimitCmd(f *Factory) *cobra.Command

NewRateLimitCmd builds the ratelimit command group.

func NewRepliesCmd

func NewRepliesCmd(f *Factory) *cobra.Command

NewRepliesCmd builds the replies command group.

func NewRootCmd

func NewRootCmd(f *Factory) *cobra.Command

NewRootCmd constructs the root command and wires subcommands.

func NewSearchCmd

func NewSearchCmd(f *Factory) *cobra.Command

NewSearchCmd builds the search command.

func NewUsersCmd

func NewUsersCmd(f *Factory) *cobra.Command

NewUsersCmd builds the users command group.

func NewUsersMeCmd

func NewUsersMeCmd(f *Factory) *cobra.Command

NewUsersMeCmd builds a top-level alias for "users me".

func NewVersionCmd

func NewVersionCmd() *cobra.Command

NewVersionCmd shows version information.

func NewWebhooksCmd

func NewWebhooksCmd(f *Factory) *cobra.Command

NewWebhooksCmd builds the webhooks command group.

func ValidateHTTPSURL

func ValidateHTTPSURL(rawURL, fieldName string) error

ValidateHTTPSURL validates that a URL uses HTTPS protocol. Returns a UserFriendlyError if validation fails.

func WrapError

func WrapError(context string, err error) error

WrapError wraps an error with context while preserving the ability to format it. Use this instead of fmt.Errorf when you want to add context but still get user-friendly error formatting.

func WriteErrorTo

func WriteErrorTo(ctx context.Context, w io.Writer, err error)

WriteErrorTo writes a formatted error to w.

In JSON output mode, this emits a structured JSON error object to avoid contaminating stdout pipelines with plain-text diagnostics.

Types

type Factory

type Factory struct {
	IO        *iocontext.IO
	Config    *config.Config
	Store     func() (secrets.Store, error)
	NewClient func(accessToken string, cfg *api.Config) (*api.Client, error)
	Output    outfmt.Format
	ColorMode outfmt.ColorMode
	Debug     bool
	Account   string
	// contains filtered or unexported fields
}

Factory provides shared dependencies and helpers for commands.

func NewFactory

func NewFactory(ctx context.Context, opts FactoryOptions) (*Factory, error)

NewFactory creates a new Factory with defaults.

func (*Factory) ActiveCredentials

func (f *Factory) ActiveCredentials(_ context.Context) (*secrets.Credentials, error)

ActiveCredentials returns the stored credentials for the active account. This is useful for avoiding extra API calls (e.g. GetMe) when we already have stable identifiers like user_id.

func (*Factory) Client

func (f *Factory) Client(ctx context.Context) (*api.Client, error)

Client returns a Threads client for the active account.

func (*Factory) Confirm

func (f *Factory) Confirm(ctx context.Context, prompt string) bool

Confirm prompts for confirmation unless --yes is set. Returns false when stdin is not a TTY.

func (*Factory) UI

func (f *Factory) UI(ctx context.Context) *ui.Printer

UI returns a configured UI printer.

type FactoryOptions

type FactoryOptions struct {
	IO        *iocontext.IO
	Config    *config.Config
	Store     func() (secrets.Store, error)
	NewClient func(accessToken string, cfg *api.Config) (*api.Client, error)
}

FactoryOptions allows overriding factory dependencies (mainly for tests).

type ListConfig

type ListConfig[T any] struct {
	Use          string
	Short        string
	Long         string
	Example      string
	Headers      []string
	RowFunc      func(T) []string
	ColumnTypes  []outfmt.ColumnType
	EmptyMessage string

	// Fetch function - called with cursor and limit
	Fetch func(ctx context.Context, client *api.Client, cursor string, limit int) (ListResult[T], error)
}

ListConfig is a generic struct for configuring list commands

type ListResult

type ListResult[T any] struct {
	Items   []T
	HasMore bool
	Cursor  string
}

ListResult is a generic struct for paginated list results

type RootOptions

type RootOptions struct {
	Account  string
	Output   string
	JSON     bool
	Color    string
	NoColor  bool
	Debug    bool
	Query    string
	Yes      bool
	NoPrompt bool
}

RootOptions captures global flags.

type UserFriendlyError

type UserFriendlyError struct {
	Message    string
	Suggestion string
	Cause      error
}

UserFriendlyError wraps an error with a user-friendly message and optional suggestion.

func (*UserFriendlyError) Error

func (e *UserFriendlyError) Error() string

func (*UserFriendlyError) Unwrap

func (e *UserFriendlyError) Unwrap() error