cli

Documentation

Overview

Package cli holds the setup logic shared by the driver-os command front-ends (cmd/agent, cmd/chat, …): resolving the LLM provider from env+flags, building the sandbox backend, and validating the safety-relevant flag combinations. It is the ONE place these decisions live, so every front-end picks a backend and enforces isolation identically. Loop/termination policy stays in package agent; this is purely the wiring a main() needs before it can call the loop.

Index

• Variables
• func BuildSandbox(ctx context.Context, kind, dir, runtime string, network bool) (sandbox.Sandbox, error)
• func BuildSandboxWithEnvAllowlist(ctx context.Context, kind, dir, runtime string, network bool, ...) (sandbox.Sandbox, error)
• func GroupedUsage(fs *flag.FlagSet, w io.Writer, header string, groups []UsageGroup) func()
• func PickProvider(provider, model string) (llm.Provider, error)
• func SplitList(s string) []string
• func SplitModelRef(ref string) (provider, model string)
• func TrustLabel(iso sandbox.Isolation) string
• func UncategorizedFlags(fs *flag.FlagSet, groups []UsageGroup) (missing, stale []string)
• func ValidateSandboxFlags(kind, runtime string, network, untrusted bool) error
• type UsageGroup

Variables

var ErrNoProviderKey = errors.New("no provider key found; set OPENROUTER_API_KEY, ANTHROPIC_API_KEY, X_AI_API_KEY, or OPENAI_API_KEY in .env (or pass -provider=ollama for a keyless local backend)")

ErrNoProviderKey is the auto-mode "no key anywhere" sentinel, so a front-end can label that specific setup failure distinctly (vs a named-provider key error).

Functions

func BuildSandbox

func BuildSandbox(ctx context.Context, kind, dir, runtime string, network bool) (sandbox.Sandbox, error)

BuildSandbox opens the isolation backend every effect flows through (see ../../sandbox + ../../docs/specs/SANDBOX.md). kind picks the backend: "local" (IsolationNone — host subprocess, TRUSTED code only) or "docker" (a resource-capped container; runtime="runsc" selects gVisor / kernel isolation, network toggles egress). The caller is responsible for Close. BuildSandbox opens a sandbox with the full ambient environment for local runs.

func BuildSandboxWithEnvAllowlist

func BuildSandboxWithEnvAllowlist(ctx context.Context, kind, dir, runtime string, network bool, envAllowlist []string) (sandbox.Sandbox, error)

BuildSandboxWithEnvAllowlist opens the isolation backend and, for a local sandbox, optionally limits inherited command environment variables by name.

func GroupedUsage

func GroupedUsage(fs *flag.FlagSet, w io.Writer, header string, groups []UsageGroup) func()

GroupedUsage returns a flag.Usage function that renders fs's flags in titled groups instead of one alphabetical wall. Flags not named in any group land in a trailing "Other" section, so a newly added flag is never invisible in -help (and a test can assert the section stays empty). The per-flag rendering follows flag.PrintDefaults conventions: name, argument type derived from backquotes in the usage string, the usage text, and a non-zero default.

func PickProvider

func PickProvider(provider, model string) (llm.Provider, error)

PickProvider resolves the LLM backend from the provider and model selectors (D6). An empty provider auto-infers from whichever key is present (the historical behavior); a NAMED provider whose key is absent is a setup error rather than a silent fallback, so a script gets the backend it asked for or a clear refusal. model overrides the provider's *_MODEL env default; the flag always wins.

func SplitList

func SplitList(s string) []string

SplitList splits a comma-separated flag value, dropping empty entries.

func SplitModelRef

func SplitModelRef(ref string) (provider, model string)

SplitModelRef splits an optional "provider:model" reference — the syntax that lets any ROLE (solver /model, planner /plan, reviewer /review) sit on a different backend than the session default, e.g. "anthropic:claude-fable-5" while the solver runs on OpenRouter. Only a prefix naming a KNOWN provider kind splits: OpenRouter model ids legitimately contain ":" (e.g. "deepseek/deepseek-chat:free"), so an unrecognized prefix leaves the ref intact as a bare model id (provider "" = caller's default).

func TrustLabel

func TrustLabel(iso sandbox.Isolation) string

TrustLabel renders how much to trust a given isolation level in a startup log, so a plain shared-kernel container is never mislabeled as safe for hostile code.

func UncategorizedFlags

func UncategorizedFlags(fs *flag.FlagSet, groups []UsageGroup) (missing, stale []string)

UncategorizedFlags returns the names fs defines that groups do not claim, and the names groups claim that fs does not define. Front-end tests assert both are empty so -help grouping can never silently drift from the flag set.

func ValidateSandboxFlags

func ValidateSandboxFlags(kind, runtime string, network, untrusted bool) error

ValidateSandboxFlags rejects nonsensical or unsafe flag COMBINATIONS up front, so a typo can't silently weaken isolation and an unsafe request is refused before any container starts. The in-loop MinIsolation gate is still the authoritative safety boundary; this is the fail-fast layer in front of it.

Types

type UsageGroup

type UsageGroup struct {
	Title string
	Flags []string // flag names in display order
}

UsageGroup is one titled section of a front-end's -help output.