cmd

package
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Oct 7, 2026 License: MIT Imports: 63 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var Version = "dev"

Version is the CLI version reported by `baseten version` and `baseten --version`. Overridden at release time via -ldflags: 

-X github.com/basetenlabs/baseten-cli/internal/cmd.Version=<semver>

Functions

func Execute 

func Execute(ctx context.Context, options ExecuteOptions) error

Execute builds the Cobra command tree and runs it.

func FormatDeploymentLogLine 

func FormatDeploymentLogLine(log managementapi.Log) string

FormatDeploymentLogLine renders a log record as "[YYYY-MM-DD HH:MM:SS]: (replica) message" in the local timezone. Replica segment is omitted when empty. Unparseable timestamps fall back to the raw string.

func GetAPIKey 

func GetAPIKey() (string, error)

GetAPIKey returns the Baseten API key from the BASETEN_API_KEY environment variable or an ErrUsage if not set.

func NewAuthStore 

func NewAuthStore(insecureStorage bool) (*auth.Store, error)

NewAuthStore creates an auth store using the default config directory.

func OAuthConfig 

func OAuthConfig(host string) *oauth2.Config

OAuthConfig returns the OAuth2 configuration for the given host.

func Register 

func Register[T any](path string, fn func(*CommandContext, *T) error)

Register associates a run function with a command path (e.g. "api management"). Panics if the path is already registered.

func ResolveTeam 

func ResolveTeam(ctx context.Context, api *managementapi.Client, input string) (string, error)

ResolveTeam translates a --team flag value (team name or team ID) into a team ID by listing teams from the management API. Returns "" when input is "" so the server can route to the org's default team.

An exact match on Id wins over a name match: this lets users always pass an ID without colliding with a same-spelled name.

func VerifyRunners 

func VerifyRunners()

VerifyRunners panics if any command with Flags is missing a registered runner, or if a runner's flag type doesn't match.

func WithExecer added in v0.4.0 

func WithExecer(ctx context.Context, e Execer) context.Context

WithExecer returns a context that overrides the Execer used by CommandContext to look up and run external commands. Intended for tests.

func WithHTTPClient 

func WithHTTPClient(ctx context.Context, c *http.Client) context.Context

WithHTTPClient returns a context that overrides the HTTP client used by CommandContext and therefore all SDK clients created from it.

func WithNow 

func WithNow(ctx context.Context, fn func() time.Time) context.Context

WithNow returns a context that pins CommandContext.Now to fn. Intended for tests; production code uses time.Now via the default path.

func WithS3APIClientFactory 

func WithS3APIClientFactory(ctx context.Context, f S3APIClientFactory) context.Context

WithS3APIClientFactory returns a context that overrides how CommandContext.NewS3APIClient builds the S3 client used for archive uploads.

func WithSleep 

func WithSleep(ctx context.Context, fn func(context.Context, time.Duration) error) context.Context

WithSleep returns a context that intercepts CommandContext.Sleep with fn. Intended for tests so polling loops complete instantly.

func WithVolumeTransfer added in v1.0.0 

func WithVolumeTransfer(ctx context.Context, t VolumeTransfer) context.Context

WithVolumeTransfer returns a context that overrides what reaches volume contents. Intended for tests.

Types

type CommandContext 

type CommandContext struct {
	context.Context
	Command      *cobra.Command
	Args         []string
	JSON         bool
	JSONCompact  bool
	JSONLines    bool
	Stdin        io.Reader
	Stdout       io.Writer
	Stderr       io.Writer
	ExitWithCode func(int)
	OpenURL      func(string) error
	// JQQuery is a compiled --jq expression installed by the framework. When
	// non-nil, [OutputJSON] and [JSONArrayWriter.Write] route their input
	// through the query before encoding. Leaves should not set this directly.
	JQQuery *gojq.Query
	// contains filtered or unexported fields
}

CommandContext is passed to run functions.

func (*CommandContext) AuthTransport added in v0.2.0 

func (c *CommandContext) AuthTransport() (*auth.Transport, *Remote, error)

AuthTransport builds an HTTP transport that injects the active session's credential on every request, regardless of the request host. Shared by the SDK clients and by commands that POST to non-SDK hosts (e.g. a Model API URL). The resolved remote is returned alongside so callers can derive URLs without resolving it again.

func (*CommandContext) ConfirmYesNo 

func (c *CommandContext) ConfirmYesNo(title string) error

ConfirmYesNo prompts the user with a yes/no question. Returns an ErrUsage when stdin is not a terminal so callers can instruct the user to pass --yes or similar. Returns a non-nil error if the user declines.

func (*CommandContext) Execer added in v0.4.0 

func (c *CommandContext) Execer() Execer

Execer returns the Execer used to run external commands, honoring any override installed via WithExecer.

func (*CommandContext) IsInteractive 

func (c *CommandContext) IsInteractive() bool

IsInteractive returns true if the context's stdin is a terminal. It asks the terminal driver rather than checking for a character device, because /dev/null is a character device without being a terminal, and redirecting stdin from it is how cron and CI usually run.

func (*CommandContext) Log 

func (c *CommandContext) Log(v string)

Log writes to stderr.

func (*CommandContext) LogLine 

func (c *CommandContext) LogLine(v string)

LogLine writes a line to stderr.

func (*CommandContext) Logf 

func (c *CommandContext) Logf(format string, args ...any)

Logf writes formatted output to stderr.

func (*CommandContext) NewInferenceClient 

func (c *CommandContext) NewInferenceClient(flags cmd.InferenceClientFlags) (*client.InferenceClient, error)

NewInferenceClient creates an inference API client that resolves credentials via the auth store.

func (*CommandContext) NewJSONArrayWriter 

func (c *CommandContext) NewJSONArrayWriter() *JSONArrayWriter

NewJSONArrayWriter returns a writer that outputs a JSON array incrementally. Call Write for each element and Close when done.

func (*CommandContext) NewManagementClient 

func (c *CommandContext) NewManagementClient() (*client.ManagementClient, error)

NewManagementClient creates a management API client that resolves credentials via the auth store (env var > stored credential).

func (*CommandContext) NewManagementClientWithAuth 

func (c *CommandContext) NewManagementClientWithAuth(mgmtURL, authHeader string) (*client.ManagementClient, error)

NewManagementClientWithAuth creates a management API client against mgmtURL with a specific auth header. Used during login to validate a credential before storing it, before any profile exists.

func (*CommandContext) NewSandboxClient added in v1.2.0 

func (c *CommandContext) NewSandboxClient(team string) (client *sandbox.Client, teamID *string, err error)

NewSandboxClient creates the high-level sandbox client. Sandbox tokens are minted through the auth store's management client, so API keys and OAuth logins both work. The team argument is a team name or ID, resolved like every other command's --team; the resolved ID is also returned, nil when no team was given, for calls through the client's generated API.

func (*CommandContext) NewVolumeTransfer added in v1.0.0 

func (c *CommandContext) NewVolumeTransfer() (VolumeTransfer, error)

NewVolumeTransfer returns what reaches volume contents, honoring any override installed via WithVolumeTransfer.

func (*CommandContext) Now 

func (c *CommandContext) Now() time.Time

Now returns the current wall-clock time, honoring any override installed via WithNow. Used by command runners for any "now" calculation so tests can pin the clock.

func (*CommandContext) Output 

func (c *CommandContext) Output(v string)

Output writes to stdout.

func (*CommandContext) OutputJSON 

func (c *CommandContext) OutputJSON(v any)

OutputJSON writes a value as JSON to stdout. Uses indentation unless JSONCompact is set. When CommandContext.JQQuery is set, the value is routed through the jq query and each result is emitted in turn; a jq runtime error is stashed on the context and surfaced by the framework after the runner returns.

func (*CommandContext) OutputLine 

func (c *CommandContext) OutputLine(v string)

OutputLine writes a line to stdout.

func (*CommandContext) OutputTable 

func (c *CommandContext) OutputTable(out TableOutput)

OutputTable writes a borderless table to stdout with bold headers. Header styling auto-degrades when stdout is not a terminal.

func (*CommandContext) Outputf 

func (c *CommandContext) Outputf(format string, args ...any)

Outputf writes formatted output to stdout.

func (*CommandContext) SetDefaultProfile added in v0.3.0 

func (c *CommandContext) SetDefaultProfile(name string)

SetDefaultProfile sets a fallback profile, used only when no profile is selected via --profile, BASETEN_API_KEY, or BASETEN_PROFILE. It must be called before anything that resolves auth (AuthTransport, NewManagementClient, NewInferenceClient, or the Remote/Session accessors): the session resolves once and is cached, so a call afterward has no effect.

func (*CommandContext) Sleep 

func (c *CommandContext) Sleep(d time.Duration) error

Sleep pauses for d, honoring any override installed via WithSleep and returning early with ctx.Err() if the context is cancelled.

func (*CommandContext) SuppressJSONError added in v1.0.0 

func (c *CommandContext) SuppressJSONError()

SuppressJSONError declares that the JSON already written to stdout reports the failure the command is about to return, so the framework must not append an error envelope after it. Call it before returning an error from a command whose payload encodes its own verdict, keeping stdout a single JSON document under --output json.

func (*CommandContext) VerboseLog 

func (c *CommandContext) VerboseLog(v string)

VerboseLog writes to stderr if verbose mode is enabled.

func (*CommandContext) VerboseLogLine 

func (c *CommandContext) VerboseLogLine(v string)

VerboseLogLine writes a line to stderr if verbose mode is enabled.

func (*CommandContext) VerboseLogf 

func (c *CommandContext) VerboseLogf(format string, args ...any)

VerboseLogf writes formatted output to stderr if verbose mode is enabled.

type DeploymentRef added in v0.3.0 

type DeploymentRef struct {
	ModelID      string
	DeploymentID string
}

DeploymentRef is the result of resolving cmd.ModelDeploymentIDFlags: a resolved model ID paired with a resolved deployment ID.

func ResolveDeploymentRef added in v0.3.0 

func ResolveDeploymentRef(
	ctx context.Context, api *managementapi.Client, flags cmd.ModelDeploymentIDFlags,
) (DeploymentRef, error)

ResolveDeploymentRef resolves the model, then the deployment within it. When --deployment-id is set it is used directly; when --deployment-name is set the deployment is looked up by exact name within the model. Absent or ambiguous name matches return an error.

type ErrSubprocess 

type ErrSubprocess struct {
	Err  error
	Code int
}

ErrSubprocess carries a raw process exit code. Used for subprocess passthrough (e.g. truss) where we want the inner exit code verbatim, bypassing the standard typed-error classification.

func (*ErrSubprocess) Error 

func (e *ErrSubprocess) Error() string

func (*ErrSubprocess) ExitCode 

func (e *ErrSubprocess) ExitCode() cmd.ExitCode

func (*ErrSubprocess) Meaning 

func (*ErrSubprocess) Meaning() string

func (*ErrSubprocess) Unwrap 

func (e *ErrSubprocess) Unwrap() error

type Execer added in v0.4.0 

type Execer interface {
	// LookPath reports whether name is an executable on PATH, like exec.LookPath.
	LookPath(name string) (string, error)
	// Exec runs cmd (already built via exec.CommandContext, so it carries the
	// command context and wired stdio/env) and returns an [ErrSubprocess] on a
	// non-zero exit so the inner exit code propagates.
	Exec(cmd *exec.Cmd) error
}

Execer looks up and runs external commands. The default uses os/exec; tests inject a fake via WithExecer to avoid spawning real processes.

type ExecuteOptions 

type ExecuteOptions struct {
	Args         []string
	Stdin        io.Reader
	Stdout       io.Writer
	Stderr       io.Writer
	ExitWithCode func(int)
	// OpenURL overrides the system browser opener.
	OpenURL func(string) error
	// StrictOutputChecks panics on output that is malformed in a way a user
	// would see but the code cannot detect for itself, such as a table row whose
	// cell count does not match its headers. Tests set it; production renders
	// whatever it was given rather than failing a command over its formatting.
	StrictOutputChecks bool
}

ExecuteOptions configures command execution.

type JSONArrayWriter 

type JSONArrayWriter struct {
	// contains filtered or unexported fields
}

JSONArrayWriter writes a JSON array to a writer incrementally.

func (*JSONArrayWriter) Close 

func (w *JSONArrayWriter) Close()

Close finishes the JSON array.

func (*JSONArrayWriter) Write 

func (w *JSONArrayWriter) Write(v any)

Write writes a single element to the JSON array. When the owning context has CommandContext.JQQuery set, the element is routed through the query and each result is emitted as its own record; runtime errors are stashed on the context and surfaced by the framework.

type ModelRef 

type ModelRef struct {
	ID   string
	Team string
}

ModelRef is the result of resolving cmd.ModelRefFlags against the management API. Team is the resolved team ID (empty when unscoped).

func ResolveModelRef 

func ResolveModelRef(
	ctx context.Context, api *managementapi.Client, flags cmd.ModelRefFlags,
) (ModelRef, error)

ResolveModelRef resolves cmd.ModelRefFlags into a ModelRef. When --model-id is set it returns immediately. When --model-name is set it resolves the optional team and looks up the model by name; absent or ambiguous matches return an error.

type Remote 

type Remote struct {
	// contains filtered or unexported fields
}

Remote captures the resolved Baseten remote (app URL + override knobs) used to derive every URL the CLI talks to. Construct once via NewRemote at the start of a command; callers use the methods rather than reading env directly.

func NewRemote 

func NewRemote(remoteURL string) (*Remote, error)

NewRemote resolves the remote URL (flag arg, then BASETEN_REMOTE_URL, then https://app.baseten.co), looks up any known per-remote URL overrides, and applies the optional override env vars on top.

func (*Remote) EnvironmentPredictURL added in v0.3.0 

func (r *Remote) EnvironmentPredictURL(modelID, environment, regionSlug string) string

EnvironmentPredictURL returns the user-facing predict URL for a model environment, whose stable name selects the live deployment via the path. regionSlug is the region of the environment's current deployment, since an environment holding a regional deployment is invoked through that deployment's per-region host.

func (*Remote) HostLabel added in v0.2.0 

func (r *Remote) HostLabel() string

HostLabel returns the remote's host without the "app." prefix or any port, used to disambiguate profile names across non-default remotes.

func (*Remote) InferenceBaseURL 

func (r *Remote) InferenceBaseURL(modelID, chainID, environment string) (string, error)

InferenceBaseURL returns the base URL (no path) for inference calls. When an inference base URL override is set, that is returned verbatim; otherwise the URL is built from the remote's scheme and management API host.

func (*Remote) InferenceHostHeader 

func (r *Remote) InferenceHostHeader(modelID, chainID, environment string) (string, bool, error)

InferenceHostHeader returns the Host header value to use for inference requests when the remote requires one. The bool reports whether the caller should force the header; when false, the default URL-derived host is fine.

func (*Remote) IsDefault added in v0.2.0 

func (r *Remote) IsDefault() bool

IsDefault reports whether this is the default Baseten remote.

func (*Remote) LogsURL 

func (r *Remote) LogsURL(modelID, deploymentID string) string

LogsURL returns the user-facing logs URL printed in push output.

func (*Remote) ManagementURL 

func (r *Remote) ManagementURL() string

ManagementURL returns the base URL for the REST management API.

func (*Remote) ModelAPIInferenceURL added in v0.2.0 

func (r *Remote) ModelAPIInferenceURL() string

ModelAPIInferenceURL returns the base URL for Model API (shared endpoint) inference on this remote, e.g. https://inference.baseten.co. OpenAI-shaped routes (e.g. /v1/chat/completions) live underneath it.

func (*Remote) PredictURL 

func (r *Remote) PredictURL(modelID, deploymentID string, isDraft bool, regionSlug string) string

PredictURL returns the user-facing predict URL printed in push output.

func (*Remote) RemoteURL 

func (r *Remote) RemoteURL() string

RemoteURL returns the raw remote URL.

type S3APIClientFactory 

type S3APIClientFactory func(aws.Config) transfermanager.S3APIClient

S3APIClientFactory builds an S3 client from a fully-populated aws.Config (region + credentials). Tests can inject a fake to capture upload calls.

type TableOutput added in v0.2.0 

type TableOutput struct {
	Headers []string
	Rows    [][]string
	// RightAlignedColumns lists column indices whose header and cells are
	// right-aligned; columns absent from the list default to left-aligned.
	RightAlignedColumns []int
}

TableOutput describes a borderless table for OutputTable.

type TailDeploymentLogsOptions 

type TailDeploymentLogsOptions struct {
	API          *managementapi.Client
	ModelID      string
	DeploymentID string

	// StopOnActive stops the tail when the deployment reaches ACTIVE. By
	// default ACTIVE is treated as a runnable state and tailing continues
	// (matching `truss model logs --tail`). push --tail --wait sets this
	// so a successful deploy ends the tail.
	StopOnActive bool

	// WarmupTimeout is how long to silently retry 404s from the logs API
	// at the start of the tail, before any successful poll. After the
	// first successful logs response, 404s are surfaced as errors. Zero
	// means no warmup retries. (Status-API 404s are never retried here.)
	WarmupTimeout time.Duration
}

TailDeploymentLogsOptions configures TailDeploymentLogs. API, ModelID, and DeploymentID are required.

type TailDeploymentLogsResult 

type TailDeploymentLogsResult struct {
	// Logs yields log records in arrival order. A non-nil error indicates
	// the stream is ending due to that error and the log pointer is nil.
	// The iterator is single-use.
	Logs iter.Seq2[*managementapi.Log, error]

	// FinalFetchedStatus returns the status as last fetched when the tail
	// loop ended. Valid only after Logs is fully consumed. Nil if the loop
	// ended before any status fetch (no logs ever arrived, or ctx was
	// cancelled during phase 1).
	FinalFetchedStatus func() *tailStatus
}

TailDeploymentLogsResult bundles the streaming log iterator with an accessor for the final fetched status.

func TailDeploymentLogs 

func TailDeploymentLogs(ctx *CommandContext, opts TailDeploymentLogsOptions) *TailDeploymentLogsResult

TailDeploymentLogs tails a specific deployment's logs. It is a thin adapter over tailLogs that wires the deployment logs and describe endpoints.

type VolumeTransfer added in v1.0.0 

type VolumeTransfer interface {
	PushVolume(context.Context, client.PushVolumeOptions) (*client.PushVolumeResult, error)
	PullVolume(context.Context, client.PullVolumeOptions) (*client.PullVolumeResult, error)
	FetchVolumeManifest(
		context.Context, client.FetchVolumeManifestOptions,
	) (*client.VolumeManifest, error)
}

VolumeTransfer reaches a volume's contents: the bytes of a version and the manifest describing its file tree. Satisfied by the management client, and an interface so tests can substitute a fake rather than speak the volume service's protocol.

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.