Help us shape the future of Go! Take the 2026 Go Developer Survey

cli

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 6, 2026 License: AGPL-3.0 Imports: 34 Imported by: 0

Documentation

Overview

Package cli owns Starport command contracts and process-independent execution.

Index

Constants

View Source 
const (
	// ExitCodeRuntime reports an application or dependency failure.
	ExitCodeRuntime = 1
	// ExitCodeUsage reports invalid command syntax or arguments.
	ExitCodeUsage = 2
)

Variables

View Source 
var (
	// ErrStdinRequired reports a missing command input stream.
	ErrStdinRequired = errors.New("command input is required")
	// ErrStdoutRequired reports a missing command output stream.
	ErrStdoutRequired = errors.New("command output is required")
	// ErrStderrRequired reports a missing command error stream.
	ErrStderrRequired = errors.New("command error output is required")
	// ErrServerRunnerRequired reports a missing server runtime boundary.
	ErrServerRunnerRequired = errors.New("server runner is required")
	// ErrInitializerRequired reports a missing setup runtime boundary.
	ErrInitializerRequired = errors.New("initializer is required")
	// ErrConfigLoaderRequired reports a missing configuration reader.
	ErrConfigLoaderRequired = errors.New("configuration loader is required")
	// ErrPathResolverRequired reports a missing platform-path reader.
	ErrPathResolverRequired = errors.New("configuration path resolver is required")
	// ErrDiagnoserRequired reports a missing diagnostic runtime boundary.
	ErrDiagnoserRequired = errors.New("diagnoser is required")
)
View Source 
var (
	// ErrDevelopmentStarterRequired reports a missing development boundary.
	ErrDevelopmentStarterRequired = errors.New("development starter is required")
	// ErrDevelopmentSessionInvalid reports an incomplete development session.
	ErrDevelopmentSessionInvalid = errors.New("development session is invalid")
)
View Source 
var ErrBaselinePromotionRefused = errors.New("baseline promotion refused")

ErrBaselinePromotionRefused reports a promotion receipt with the refused status.

View Source 
var ErrDiagnosisFailed = errors.New("diagnosis failed")

ErrDiagnosisFailed reports one or more failed diagnostic checks.

View Source 
var ErrNoClipboard = errors.New(
	"no clipboard command was found on this machine; pipe the link instead, " +
		"for example `starport auth url | pbcopy`",
)

ErrNoClipboard reports a machine with no clipboard command this build knows how to drive. It names the alternative, because piping the URL is what an operator would have done anyway and the command still printed it.

Functions

func ExitCode 

func ExitCode(err error) int

ExitCode maps a command error to a process exit code.

func New 

func New(deps Dependencies) (*urfavecli.Command, error)

New creates the Starport root command.

func Run 

func Run(ctx context.Context, args []string, deps Dependencies) error

Run builds and executes the command for the supplied argument slice.

func WriteVersion 

func WriteVersion(w io.Writer, info BuildInfo, asJSON bool) error

WriteVersion writes build information in text or JSON format.

Types

type BackupCapturer added in v1.3.0 

type BackupCapturer func(context.Context, *config.Config, recovery.CaptureRequest) (recovery.CaptureResult, error)

BackupCapturer captures the stopped deployment selected by configuration.

type BackupCloser added in v1.3.0 

type BackupCloser func(context.Context, *config.Config) (recovery.Record, error)

BackupCloser closes recovery approval without starting a gateway.

type BackupFilePublisher added in v1.3.0 

type BackupFilePublisher func(context.Context, *config.Config, recovery.PublishFilesRequest) (recovery.PublishFilesResult, error)

BackupFilePublisher validates and publishes one canonical role without starting the gateway.

type BackupPreparer added in v1.3.0 

type BackupPreparer func(context.Context, *config.Config, recovery.PrepareRequest) (recovery.PrepareResult, error)

BackupPreparer imports a verified backup into configured isolated targets.

type BackupVerifier added in v1.3.0 

type BackupVerifier func(context.Context, *config.Config, recovery.VerifyRequest) (recovery.CaptureResult, error)

BackupVerifier verifies a bundle without opening live stores.

type BaselinePromoter added in v1.3.0 

type BaselinePromoter func(context.Context, *config.Config, runtimecatalog.PromotionRequest, time.Duration, PromotionRecorded) (runtimecatalog.PromotionReceipt, error)

BaselinePromoter records a request to make the packaged baseline of this binary the retained fleet baseline. It waits for the outcome from the lease holder until the wait ends.

type BaselineStatusReader added in v1.3.0 

type BaselineStatusReader func(context.Context, *config.Config) (runtimecatalog.BaselineReport, error)

BaselineStatusReader compares the packaged baseline of this binary with the retained fleet baseline.

type BrowserOpener added in v1.1.0 

type BrowserOpener func(url string) error

BrowserOpener opens a URL in the operator's browser.

type BuildInfo 

type BuildInfo struct {
	Version   string `json:"version"`
	BuildTime string `json:"build_time"`
	GitCommit string `json:"git_commit"`
	GitBranch string `json:"git_branch"`
	GoVersion string `json:"go_version"`
	OS        string `json:"os"`
	Arch      string `json:"arch"`
}

BuildInfo contains immutable binary build information.

type ClipboardWriter added in v1.1.0 

type ClipboardWriter func(ctx context.Context, text string) error

ClipboardWriter puts text on the operator's clipboard. It takes a context because the real implementation runs another program, and an operator who interrupts the command should not be left waiting on a wedged one.

type ConfigLoader 

type ConfigLoader func(context.Context) (*config.Config, error)

ConfigLoader reads and validates effective configuration.

type ConfigurationApplier added in v1.3.0 

type ConfigurationApplier func(context.Context, *config.Config, configrevision.ApplyRequest) (configrevision.Result, error)

ConfigurationApplier commits the next shared revision and fences the fleet.

type ConfigurationMigrator added in v1.3.0 

type ConfigurationMigrator func(context.Context, *config.Config, string, configrevision.Request) (configrevision.Result, error)

ConfigurationMigrator records a configuration authority switch.

type Dependencies 

type Dependencies struct {
	Stdin            io.Reader
	Stdout           io.Writer
	Stderr           io.Writer
	Build            BuildInfo
	RunServer        ServerRunner
	StartDevelopment DevelopmentStarter
	Initialize       Initializer
	LoadConfig       ConfigLoader
	ResolvePaths     PathResolver
	Diagnose         Diagnoser
	MigrateRuntime   RuntimeMigrator
	InitializeFleet  FleetInitializer
	// The catalog baseline commands. Each is optional: a command whose
	// dependency is absent reports a runtime failure.
	PromoteCatalogBaseline BaselinePromoter
	CatalogBaselineStatus  BaselineStatusReader
	// The configuration authority commands. Each is optional: a command
	// whose dependency is absent reports a runtime failure.
	InitializeSharedConfiguration SharedConfigurationInitializer
	MigrateConfiguration          ConfigurationMigrator
	ApplyConfiguration            ConfigurationApplier
	EffectiveConfiguration        EffectiveConfigurationReader
	CloseBackupBoundary           BackupCloser
	CaptureBackup                 BackupCapturer
	VerifyBackup                  BackupVerifier
	PrepareBackup                 BackupPreparer
	InspectImportedBackup         ImportedBackupInspector
	ApplyImportedHistory          ImportedHistoryApplier
	WriteImportedHistory          ImportedHistoryWriter
	PublishBackupFiles            BackupFilePublisher
	ActivateRecovery              RecoveryActivator
	InspectRecoveryActivation     RecoveryActivationInspector
	PreparePopulatedRecovery      PopulatedRecoveryPreparer
	ActivatePopulatedRecovery     PopulatedRecoveryActivator
	InspectPopulatedRecovery      PopulatedRecoveryInspector
	// Docs supplies the embedded documentation site for docs export. An
	// absent source reports that the build has no documentation site.
	Docs DocsSource
	// Desktop provides browser and clipboard access. Dependency checks do not require these services.
	// Commands print each link even when neither service is available.
	Desktop Desktop
	// ExtraCommands appends process-owned commands to the root command tree.
	// The process boundary owns commands whose behavior binds to its build,
	// such as the embedded agent skill and the catalog verbs.
	ExtraCommands []*urfavecli.Command
}

Dependencies contains all runtime boundaries used by commands.

type Desktop added in v1.1.0 

type Desktop struct {
	OpenBrowser     BrowserOpener
	CopyToClipboard ClipboardWriter
	IsTerminal      TerminalCheck
}

Desktop reaches the machine the operator is sitting at: their browser, their clipboard, and whether anyone is watching the output at all.

Every field is optional, and a nil field selects the real implementation. The three travel together because they answer one question — what this run can do beyond writing text — and a test that wants to observe one usually wants to fix the others too.

type DevelopmentSession added in v1.0.3 

type DevelopmentSession struct {
	URL    string
	APIKey string
	// ConsoleURL signs one browser in to this session. It is a separate value
	// from URL and from APIKey because it is a separate credential: it opens a
	// console session and grants no gateway API key, and it is spent the first
	// time it is followed.
	ConsoleURL string
	// AuthDisabled reports that the session serves requests without a gateway
	// API key. It is what makes an empty APIKey legitimate rather than a bug.
	AuthDisabled bool
	Run          func(context.Context) error
	Close        func(context.Context) error
}

DevelopmentSession contains one ephemeral gateway and its one-time key.

type DevelopmentStarter added in v1.0.3 

type DevelopmentStarter func(context.Context, GatewayOptions) (DevelopmentSession, error)

DevelopmentStarter creates one isolated local gateway session.

type Diagnoser 

type Diagnoser func(context.Context, diagnosis.Options) diagnosis.Report

Diagnoser runs read-only startup checks.

type DocsSource added in v1.3.0 

type DocsSource func() (fs.FS, bool)

DocsSource returns the documentation site that the build embeds. It returns false when the build has no documentation site.

type EffectiveConfigurationReader added in v1.3.0 

type EffectiveConfigurationReader func(context.Context, *config.Config) (config.EffectiveReport, error)

EffectiveConfigurationReader reports each catalog setting and its authority.

type FleetInitializer added in v1.3.0 

type FleetInitializer func(context.Context, *config.Config, recovery.FreshRequest) (recovery.Record, error)

FleetInitializer approves an explicitly selected fresh shared deployment.

type GatewayOptions added in v1.1.0 

type GatewayOptions struct {
	// DisableAuth serves requests without a gateway API key.
	DisableAuth bool
	// AllowRemoteNoAuth acknowledges an unauthenticated gateway on an address
	// the network can reach. It lifts a startup refusal and nothing else.
	AllowRemoteNoAuth bool
}

GatewayOptions carries gateway choices for one command run. Other settings come from the environment and configuration file. These fields let an operator override settings without editing either source.

type ImportedBackupInspector added in v1.3.0 

type ImportedBackupInspector func(context.Context, *config.Config, recovery.InspectImportRequest) (recovery.ImportInspectionResult, error)

ImportedBackupInspector checks closed imported targets without approving activation.

type ImportedHistoryApplier added in v1.3.0 

type ImportedHistoryApplier func(context.Context, *config.Config, recovery.ApplyHistoryRequest) (recovery.HistoryReplayReport, error)

ImportedHistoryApplier accepts independent evidence and leaves admission closed.

type ImportedHistoryWriter added in v1.3.0 

type ImportedHistoryWriter func(context.Context, *config.Config, recovery.WriteHistoryRequest) (recovery.HistoryWriteReport, error)

ImportedHistoryWriter writes a final-only history package and leaves every target store unchanged.

type InitOptions 

type InitOptions struct {
	APIKeyName        string
	ConfiguredStorage bool
}

InitOptions contains explicit local initialization choices.

type InitResult 

type InitResult struct {
	APIKeyName string                      `json:"api_key_name"`
	ConfigFile string                      `json:"config_file,omitempty"`
	DataDir    string                      `json:"data_dir,omitempty"`
	APIKey     string                      `json:"api_key"`
	Rollback   func(context.Context) error `json:"-"`
}

InitResult contains initialized paths and the one-time gateway credential.

type Initializer 

type Initializer func(context.Context, InitOptions) (InitResult, error)

Initializer creates local state and returns the new gateway credential once.

type PathResolver 

type PathResolver func() (config.Paths, error)

PathResolver resolves platform configuration and data paths.

type PopulatedRecoveryActivator added in v1.3.0 

type PopulatedRecoveryActivator func(context.Context, *config.Config, PopulatedRecoveryRequest) (recovery.ActivationResult, error)

PopulatedRecoveryActivator claims the populated targets and completes the shared activation phases.

type PopulatedRecoveryInspector added in v1.3.0 

type PopulatedRecoveryInspector func(context.Context, *config.Config, PopulatedRecoveryRequest) (recovery.ActivationResult, error)

PopulatedRecoveryInspector reads completion and permission without changing recovery state.

type PopulatedRecoveryPreparation added in v1.3.0 

type PopulatedRecoveryPreparation struct {
	PreparedSHA256 string `json:"prepared_sha256"`
	NextAction     string `json:"next_action"`
}

PopulatedRecoveryPreparation reports the retained prepared record digest.

type PopulatedRecoveryPreparer added in v1.3.0 

type PopulatedRecoveryPreparer func(context.Context, *config.Config, PopulatedRecoveryRequest) (PopulatedRecoveryPreparation, error)

PopulatedRecoveryPreparer verifies C and H and retains the native control observation without a claim.

type PopulatedRecoveryRequest added in v1.3.0 

type PopulatedRecoveryRequest struct {
	Activation             recovery.ActivationRequest
	PriorApproval          recovery.Record
	PreparationDirectory   string
	ExpectedPreparedSHA256 string
}

PopulatedRecoveryRequest is the private operator request for populated in-place adoption. Activation names the capture C of the fenced live deployment and the history H that binds it. PriorApproval is the last open witness record that the operator retained independently. PreparationDirectory is an existing private directory that retains the prepared record.

func (PopulatedRecoveryRequest) Format added in v1.3.0 

func (PopulatedRecoveryRequest) Format(state fmt.State, _ rune)

Format excludes operator evidence, the prior approval, and private source paths.

type PromotionRecorded added in v1.3.0 

type PromotionRecorded func(record runtimecatalog.PromotionRecord, leader string)

PromotionRecorded receives the pending request and the lease holder that executes it. The holder is empty when no gateway leads the fleet.

type RecoveryActivationInspector added in v1.3.0 

type RecoveryActivationInspector func(context.Context, *config.Config, recovery.ActivationRequest) (recovery.ActivationResult, error)

RecoveryActivationInspector reads completion and permission without changing recovery state.

type RecoveryActivator added in v1.3.0 

type RecoveryActivator func(context.Context, *config.Config, recovery.ActivationRequest) (recovery.ActivationResult, error)

RecoveryActivator completes the stopped deployment's coordinated recovery procedure.

type RuntimeMigrator added in v1.3.0 

type RuntimeMigrator func(context.Context, *config.Config, string, catalog.RuntimeMigration) (catalog.RuntimeMigrationResult, error)

RuntimeMigrator executes one durable phase without starting the gateway.

type ServerRunner 

type ServerRunner func(context.Context, GatewayOptions) error

ServerRunner starts the gateway and blocks until it stops.

type SharedConfigurationInitializer added in v1.3.0 

type SharedConfigurationInitializer func(context.Context, *config.Config, configrevision.Request) (configrevision.Result, error)

SharedConfigurationInitializer writes, or previews, revision 1 of the shared deployment configuration.

type TerminalCheck added in v1.1.0 

type TerminalCheck func(writer io.Writer) bool

TerminalCheck reports whether a command's output reaches a person.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.