From f52213861a955f3af4d98e315e86db9d47c18fce Mon Sep 17 00:00:00 2001
From: Tyler Fong <tylerf@nvidia.com>
Date: Thu, 16 Apr 2026 16:38:03 -0700
Subject: [PATCH 1/5] boiler for launchable create flow

---
 pkg/cmd/cmd.go                    |   2 +
 pkg/cmd/launchable/create.go      | 782 ++++++++++++++++++++++++++++++
 pkg/cmd/launchable/create_test.go | 133 +++++
 pkg/cmd/launchable/launchable.go  |  29 ++
 pkg/store/launchable.go           |  92 ++++
 5 files changed, 1038 insertions(+)
 create mode 100644 pkg/cmd/launchable/create.go
 create mode 100644 pkg/cmd/launchable/create_test.go
 create mode 100644 pkg/cmd/launchable/launchable.go
 create mode 100644 pkg/store/launchable.go

diff --git a/pkg/cmd/cmd.go b/pkg/cmd/cmd.go
index 6912df3a..cfbe9d98 100644
--- a/pkg/cmd/cmd.go
+++ b/pkg/cmd/cmd.go
@@ -27,6 +27,7 @@ import (
 	"github.com/brevdev/brev-cli/pkg/cmd/importideconfig"
 	"github.com/brevdev/brev-cli/pkg/cmd/initfile"
 	"github.com/brevdev/brev-cli/pkg/cmd/invite"
+	"github.com/brevdev/brev-cli/pkg/cmd/launchable"
 	"github.com/brevdev/brev-cli/pkg/cmd/login"
 	"github.com/brevdev/brev-cli/pkg/cmd/logout"
 	"github.com/brevdev/brev-cli/pkg/cmd/ls"
@@ -322,6 +323,7 @@ func createCmdTree(cmd *cobra.Command, t *terminal.Terminal, loginCmdStore *stor
 	cmd.AddCommand(scale.NewCmdScale(t, noLoginCmdStore))
 	cmd.AddCommand(gpusearch.NewCmdGPUSearch(t, noLoginCmdStore))
 	cmd.AddCommand(gpucreate.NewCmdGPUCreate(t, loginCmdStore))
+	cmd.AddCommand(launchable.NewCmdLaunchable(t, loginCmdStore))
 	cmd.AddCommand(configureenvvars.NewCmdConfigureEnvVars(t, loginCmdStore))
 	cmd.AddCommand(importideconfig.NewCmdImportIDEConfig(t, noLoginCmdStore))
 	cmd.AddCommand(shell.NewCmdShell(t, loginCmdStore, noLoginCmdStore))
diff --git a/pkg/cmd/launchable/create.go b/pkg/cmd/launchable/create.go
new file mode 100644
index 00000000..275bc964
--- /dev/null
+++ b/pkg/cmd/launchable/create.go
@@ -0,0 +1,782 @@
+package launchable
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"os"
+	"regexp"
+	"strconv"
+	"strings"
+
+	"github.com/brevdev/brev-cli/pkg/cmd/cmderrors"
+	"github.com/brevdev/brev-cli/pkg/cmd/gpusearch"
+	"github.com/brevdev/brev-cli/pkg/config"
+	breverrors "github.com/brevdev/brev-cli/pkg/errors"
+	"github.com/brevdev/brev-cli/pkg/store"
+	"github.com/brevdev/brev-cli/pkg/terminal"
+	"github.com/spf13/cobra"
+)
+
+const (
+	defaultLaunchableViewAccess = "public"
+	defaultLaunchableMode       = "vm"
+	defaultFlexibleStorageGiB   = 256
+	maxLifecycleScriptBytes     = 16 * 1024
+	maxCTAServiceCount          = 2
+)
+
+type launchableCreateOptions struct {
+	Name              string
+	Description       string
+	ViewAccess        string
+	Mode              string
+	InstanceType      string
+	Storage           string
+	FileURL           string
+	Jupyter           bool
+	LifecycleScript   string
+	LifecycleFilePath string
+	ComposeURL        string
+	ComposeFilePath   string
+	ComposeYAML       string
+	SecureLinks       []string
+	FirewallRules     []string
+	DryRun            bool
+}
+
+type secureLinkSpec struct {
+	Name     string
+	Port     int
+	CTA      bool
+	CTALabel string
+}
+
+type firewallRuleSpec struct {
+	Ports      string
+	AllowedIPs string
+	StartPort  int
+	EndPort    int
+}
+
+var (
+	githubDirectoryURLPattern = regexp.MustCompile(`^https://github\.com/[A-Za-z0-9_-]+/[A-Za-z0-9_.-]+/tree/[A-Za-z0-9_.-]+(?:/[\S]*)?$`)
+	gitlabDirectoryURLPattern = regexp.MustCompile(`^https://gitlab\.com/(?:[A-Za-z0-9_-]+/)*[A-Za-z0-9_.-]+/-/tree/[A-Za-z0-9_.-]+(?:/[\S]*)?$`)
+	sizePattern               = regexp.MustCompile(`(?i)^([0-9]+(?:\.[0-9]+)?)([a-z]+)$`)
+)
+
+func NewCmdLaunchableCreate(t *terminal.Terminal, launchableStore LaunchableCmdStore) *cobra.Command { //nolint:funlen // easier to read with flags close to command
+	var opts launchableCreateOptions
+
+	cmd := &cobra.Command{
+		Use:                   "create [name]",
+		DisableFlagsInUseLine: true,
+		Short:                 "Create a launchable",
+		Long: `Create a Brev launchable using VM or Docker Compose configuration.
+
+Every supported setting in the current launchable create flow is exposed as flags,
+including view access, storage, file source, networking, lifecycle scripts, and
+Docker Compose source selection.`,
+		Example: `
+  brev launchable create demo-vm --mode vm --instance-type n2-standard-4 \
+    --description "My VM launchable" --jupyter \
+    --lifecycle-script-file ./setup.sh \
+    --secure-link name=notebook,port=8888,cta=true,cta-label=OpenNotebook
+
+  brev launchable create demo-compose --mode compose --instance-type g5.xlarge \
+    --compose-file ./docker-compose.yml --file-url https://github.com/acme/demo \
+    --secure-link name=web,port=3000,cta=true \
+    --firewall-rule ports=8000-8100,allowed-ips=user-ip
+`,
+		Args: cmderrors.TransformToValidationError(cobra.MaximumNArgs(1)),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if len(args) > 0 && opts.Name == "" {
+				opts.Name = args[0]
+			}
+
+			err := runLaunchableCreate(t, launchableStore, opts)
+			if err != nil {
+				return breverrors.WrapAndTrace(err)
+			}
+			return nil
+		},
+	}
+
+	cmd.Flags().StringVarP(&opts.Name, "name", "n", "", "Launchable name (or pass as first argument)")
+	cmd.Flags().StringVar(&opts.Description, "description", "", "Launchable description")
+	cmd.Flags().StringVar(&opts.ViewAccess, "view-access", defaultLaunchableViewAccess, "Launchable visibility: public, organization, or published")
+	cmd.Flags().StringVarP(&opts.Mode, "mode", "m", defaultLaunchableMode, "Launchable build mode: vm or compose")
+	cmd.Flags().StringVarP(&opts.InstanceType, "instance-type", "t", "", "Instance type to use for this launchable")
+	cmd.Flags().StringVar(&opts.Storage, "storage", "", "Root disk size in GiB for instance types with flexible storage")
+	cmd.Flags().StringVar(&opts.FileURL, "file-url", "", "Public notebook, markdown, or git repo URL to preload into the launchable")
+	cmd.Flags().BoolVar(&opts.Jupyter, "jupyter", true, "Install Jupyter on the host (applies to vm and compose modes)")
+	cmd.Flags().StringVar(&opts.LifecycleScript, "lifecycle-script", "", "Inline lifecycle script for VM mode")
+	cmd.Flags().StringVar(&opts.LifecycleFilePath, "lifecycle-script-file", "", "Path to a lifecycle script file for VM mode")
+	cmd.Flags().StringVar(&opts.ComposeURL, "compose-url", "", "Public Docker Compose URL")
+	cmd.Flags().StringVar(&opts.ComposeFilePath, "compose-file", "", "Path to a local Docker Compose file")
+	cmd.Flags().StringVar(&opts.ComposeYAML, "compose-yaml", "", "Inline Docker Compose YAML")
+	cmd.Flags().StringArrayVar(&opts.SecureLinks, "secure-link", nil, "Expose a secure link: name=<name>,port=<port>[,cta=true][,cta-label=<label>]")
+	cmd.Flags().StringArrayVar(&opts.FirewallRules, "firewall-rule", nil, "Add a firewall rule: ports=<port|start-end>[,allowed-ips=all|user-ip]")
+	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "Print the launchable request JSON without creating it")
+
+	return cmd
+}
+
+func runLaunchableCreate(t *terminal.Terminal, launchableStore LaunchableCmdStore, opts launchableCreateOptions) error {
+	err := validateCreateOptions(opts)
+	if err != nil {
+		return err
+	}
+
+	org, err := launchableStore.GetActiveOrganizationOrDefault()
+	if err != nil {
+		return breverrors.WrapAndTrace(err)
+	}
+	if org == nil {
+		return breverrors.NewValidationError("no active organization found; run `brev org set <NAME>` or create an organization first")
+	}
+
+	instanceTypes, err := launchableStore.GetAllInstanceTypesWithWorkspaceGroups(org.ID)
+	if err != nil {
+		return breverrors.WrapAndTrace(err)
+	}
+
+	selectedInstance, err := getSelectedInstanceType(instanceTypes, opts.InstanceType)
+	if err != nil {
+		return err
+	}
+
+	storageValue, err := resolveStorageValue(*selectedInstance, opts.Storage)
+	if err != nil {
+		return err
+	}
+
+	fileURL, err := normalizeOptionalFileURL(opts.FileURL)
+	if err != nil {
+		return err
+	}
+
+	lifecycleScript, err := resolveLifecycleScript(opts)
+	if err != nil {
+		return err
+	}
+
+	secureLinks, err := parseSecureLinks(opts.SecureLinks)
+	if err != nil {
+		return err
+	}
+
+	firewallRules, err := parseFirewallRules(opts.FirewallRules)
+	if err != nil {
+		return err
+	}
+
+	err = validatePortConflicts(secureLinks, firewallRules)
+	if err != nil {
+		return err
+	}
+
+	dockerCompose, err := resolveDockerCompose(launchableStore, opts)
+	if err != nil {
+		return err
+	}
+
+	req := buildCreateEnvironmentLaunchableRequest(opts, *selectedInstance, storageValue, fileURL, lifecycleScript, dockerCompose, secureLinks, firewallRules)
+
+	if opts.DryRun {
+		body, err := json.MarshalIndent(req, "", "  ")
+		if err != nil {
+			return breverrors.WrapAndTrace(err)
+		}
+		t.Vprint(string(body))
+		return nil
+	}
+
+	res, err := launchableStore.CreateEnvironmentLaunchable(org.ID, req)
+	if err != nil {
+		return breverrors.WrapAndTrace(err)
+	}
+
+	t.Vprint(t.Green(fmt.Sprintf("Created launchable %q (%s)", req.Name, res.ID)))
+	t.Vprint(fmt.Sprintf("Deploy URL: %s", buildLaunchableDeployURL(res.ID)))
+
+	return nil
+}
+
+func validateCreateOptions(opts launchableCreateOptions) error {
+	if strings.TrimSpace(opts.Name) == "" {
+		return breverrors.NewValidationError("launchable name is required")
+	}
+	if strings.TrimSpace(opts.InstanceType) == "" {
+		return breverrors.NewValidationError("--instance-type is required")
+	}
+
+	switch opts.ViewAccess {
+	case "public", "organization", "published":
+	default:
+		return breverrors.NewValidationError("--view-access must be one of: public, organization, published")
+	}
+
+	switch opts.Mode {
+	case "vm", "compose":
+	default:
+		return breverrors.NewValidationError("--mode must be one of: vm, compose")
+	}
+
+	if opts.LifecycleScript != "" && opts.LifecycleFilePath != "" {
+		return breverrors.NewValidationError("--lifecycle-script and --lifecycle-script-file are mutually exclusive")
+	}
+
+	composeSources := 0
+	for _, source := range []string{opts.ComposeURL, opts.ComposeFilePath, opts.ComposeYAML} {
+		if strings.TrimSpace(source) != "" {
+			composeSources++
+		}
+	}
+
+	if opts.Mode == "vm" {
+		if composeSources > 0 {
+			return breverrors.NewValidationError("--compose-url, --compose-file, and --compose-yaml are only valid with --mode compose")
+		}
+		return nil
+	}
+
+	if opts.Mode == "compose" {
+		if opts.LifecycleScript != "" || opts.LifecycleFilePath != "" {
+			return breverrors.NewValidationError("lifecycle script flags are only valid with --mode vm")
+		}
+		if composeSources != 1 {
+			return breverrors.NewValidationError("exactly one of --compose-url, --compose-file, or --compose-yaml is required with --mode compose")
+		}
+	}
+
+	return nil
+}
+
+func getSelectedInstanceType(allInstanceTypes *gpusearch.AllInstanceTypesResponse, instanceType string) (*gpusearch.InstanceType, error) {
+	if allInstanceTypes == nil {
+		return nil, breverrors.NewValidationError("no instance types were returned for your organization")
+	}
+
+	for i := range allInstanceTypes.AllInstanceTypes {
+		if allInstanceTypes.AllInstanceTypes[i].Type == instanceType {
+			if len(allInstanceTypes.AllInstanceTypes[i].WorkspaceGroups) == 0 {
+				return nil, breverrors.NewValidationError(fmt.Sprintf("instance type %q does not have a workspace group for this organization", instanceType))
+			}
+			return &allInstanceTypes.AllInstanceTypes[i], nil
+		}
+	}
+
+	return nil, breverrors.NewValidationError(fmt.Sprintf("instance type %q is not available in the active organization", instanceType))
+}
+
+func resolveStorageValue(instanceType gpusearch.InstanceType, requested string) (string, error) {
+	if len(instanceType.SupportedStorage) == 0 {
+		if requested != "" {
+			return "", breverrors.NewValidationError(fmt.Sprintf("instance type %q does not expose configurable storage; omit --storage", instanceType.Type))
+		}
+		return "", nil
+	}
+
+	storage := instanceType.SupportedStorage[0]
+	if storage.MinSize != "" && storage.MaxSize != "" {
+		minGiB, err := parseSizeToGiB(storage.MinSize)
+		if err != nil {
+			return "", err
+		}
+		maxGiB, err := parseSizeToGiB(storage.MaxSize)
+		if err != nil {
+			return "", err
+		}
+
+		value := strings.TrimSpace(requested)
+		if value == "" {
+			defaultGiB := defaultFlexibleStorageGiB
+			if minGiB > 0 && defaultGiB < minGiB {
+				defaultGiB = minGiB
+			}
+			if maxGiB > 0 && defaultGiB > maxGiB {
+				defaultGiB = maxGiB
+			}
+			value = strconv.Itoa(defaultGiB)
+		}
+
+		sizeGiB, err := strconv.Atoi(value)
+		if err != nil || sizeGiB <= 0 {
+			return "", breverrors.NewValidationError("--storage must be a positive integer number of GiB")
+		}
+		if minGiB > 0 && sizeGiB < minGiB {
+			return "", breverrors.NewValidationError(fmt.Sprintf("--storage must be at least %d GiB for instance type %q", minGiB, instanceType.Type))
+		}
+		if maxGiB > 0 && sizeGiB > maxGiB {
+			return "", breverrors.NewValidationError(fmt.Sprintf("--storage must be at most %d GiB for instance type %q", maxGiB, instanceType.Type))
+		}
+
+		return strconv.Itoa(sizeGiB), nil
+	}
+
+	if requested != "" {
+		return "", breverrors.NewValidationError(fmt.Sprintf("instance type %q uses fixed storage; omit --storage", instanceType.Type))
+	}
+
+	return "", nil
+}
+
+func resolveLifecycleScript(opts launchableCreateOptions) (string, error) {
+	if opts.Mode != "vm" {
+		return "", nil
+	}
+
+	var script string
+	switch {
+	case opts.LifecycleFilePath != "":
+		content, err := os.ReadFile(opts.LifecycleFilePath)
+		if err != nil {
+			return "", breverrors.WrapAndTrace(err)
+		}
+		script = string(content)
+	case opts.LifecycleScript != "":
+		script = opts.LifecycleScript
+	default:
+		return "", nil
+	}
+
+	err := validateLifecycleScript(script)
+	if err != nil {
+		return "", err
+	}
+
+	return script, nil
+}
+
+func validateLifecycleScript(script string) error {
+	if strings.TrimSpace(script) == "" {
+		return nil
+	}
+	if len([]byte(script)) > maxLifecycleScriptBytes {
+		return breverrors.NewValidationError("--lifecycle-script exceeds the 16 KiB limit")
+	}
+	if !strings.HasPrefix(strings.TrimSpace(script), "#!/bin/bash") {
+		return breverrors.NewValidationError("lifecycle scripts must start with #!/bin/bash")
+	}
+	return nil
+}
+
+func normalizeOptionalFileURL(raw string) (string, error) {
+	if strings.TrimSpace(raw) == "" {
+		return "", nil
+	}
+	err := validateFileURL(raw)
+	if err != nil {
+		return "", err
+	}
+	return replaceBlobWithRaw(strings.TrimSpace(raw)), nil
+}
+
+func validateFileURL(raw string) error {
+	trimmed := strings.TrimSpace(raw)
+	if strings.HasSuffix(trimmed, "/") {
+		return breverrors.NewValidationError("invalid URL: remove the trailing slash")
+	}
+	if githubDirectoryURLPattern.MatchString(trimmed) || gitlabDirectoryURLPattern.MatchString(trimmed) {
+		return breverrors.NewValidationError("invalid URL: provide a repository or file URL, not a directory URL")
+	}
+	return nil
+}
+
+func replaceBlobWithRaw(raw string) string {
+	if strings.Contains(raw, "github.com") && strings.Contains(raw, "/blob/") {
+		return strings.Replace(raw, "/blob/", "/raw/", 1)
+	}
+	if strings.Contains(raw, "gitlab.com") && strings.Contains(raw, "/-/blob/") {
+		return strings.Replace(raw, "/-/blob/", "/-/raw/", 1)
+	}
+	return raw
+}
+
+func parseSecureLinks(rawLinks []string) ([]secureLinkSpec, error) {
+	if len(rawLinks) == 0 {
+		return nil, nil
+	}
+
+	links := make([]secureLinkSpec, 0, len(rawLinks))
+	nameSet := map[string]struct{}{}
+	ctaCount := 0
+
+	for _, raw := range rawLinks {
+		values, err := parseFlagAssignments(raw)
+		if err != nil {
+			return nil, err
+		}
+
+		name := strings.TrimSpace(values["name"])
+		if name == "" {
+			return nil, breverrors.NewValidationError("each --secure-link must include name=<value>")
+		}
+		if msg := validateTunnelName(name); msg != "" {
+			return nil, breverrors.NewValidationError(fmt.Sprintf("invalid secure link name %q: %s", name, msg))
+		}
+		if _, exists := nameSet[name]; exists {
+			return nil, breverrors.NewValidationError(fmt.Sprintf("duplicate secure link name %q", name))
+		}
+		nameSet[name] = struct{}{}
+
+		portText := strings.TrimSpace(values["port"])
+		if portText == "" {
+			return nil, breverrors.NewValidationError(fmt.Sprintf("secure link %q is missing port=<value>", name))
+		}
+		if strings.Contains(portText, "-") {
+			return nil, breverrors.NewValidationError(fmt.Sprintf("secure link %q must use a single port, not a port range", name))
+		}
+
+		port, err := strconv.Atoi(portText)
+		if err != nil || port < 1 || port > 65535 {
+			return nil, breverrors.NewValidationError(fmt.Sprintf("secure link %q must use a port between 1 and 65535", name))
+		}
+
+		cta := false
+		if rawCTA, ok := values["cta"]; ok && strings.TrimSpace(rawCTA) != "" {
+			cta, err = strconv.ParseBool(strings.TrimSpace(rawCTA))
+			if err != nil {
+				return nil, breverrors.NewValidationError(fmt.Sprintf("secure link %q has invalid cta value %q; use true or false", name, rawCTA))
+			}
+		}
+
+		ctaLabel := strings.TrimSpace(values["cta-label"])
+		if ctaLabel != "" && !cta {
+			return nil, breverrors.NewValidationError(fmt.Sprintf("secure link %q cannot set cta-label without cta=true", name))
+		}
+		if cta {
+			ctaCount++
+		}
+
+		links = append(links, secureLinkSpec{
+			Name:     name,
+			Port:     port,
+			CTA:      cta,
+			CTALabel: ctaLabel,
+		})
+	}
+
+	if ctaCount > maxCTAServiceCount {
+		return nil, breverrors.NewValidationError(fmt.Sprintf("at most %d secure links can have cta=true", maxCTAServiceCount))
+	}
+
+	return links, nil
+}
+
+func parseFirewallRules(rawRules []string) ([]firewallRuleSpec, error) {
+	if len(rawRules) == 0 {
+		return nil, nil
+	}
+
+	rules := make([]firewallRuleSpec, 0, len(rawRules))
+	for _, raw := range rawRules {
+		values, err := parseFlagAssignments(raw)
+		if err != nil {
+			return nil, err
+		}
+
+		ports := strings.TrimSpace(values["ports"])
+		if ports == "" {
+			return nil, breverrors.NewValidationError("each --firewall-rule must include ports=<port|start-end>")
+		}
+
+		start, end, err := parsePortRange(ports)
+		if err != nil {
+			return nil, err
+		}
+
+		allowedIPs := strings.TrimSpace(values["allowed-ips"])
+		if allowedIPs == "" {
+			allowedIPs = "all"
+		}
+		if allowedIPs != "all" && allowedIPs != "user-ip" {
+			return nil, breverrors.NewValidationError(fmt.Sprintf("firewall rule %q has invalid allowed-ips %q; use all or user-ip", ports, allowedIPs))
+		}
+
+		rules = append(rules, firewallRuleSpec{
+			Ports:      ports,
+			AllowedIPs: allowedIPs,
+			StartPort:  start,
+			EndPort:    end,
+		})
+	}
+
+	return rules, nil
+}
+
+func validatePortConflicts(secureLinks []secureLinkSpec, firewallRules []firewallRuleSpec) error {
+	portOwners := map[int]string{}
+	for _, link := range secureLinks {
+		if owner, exists := portOwners[link.Port]; exists {
+			return breverrors.NewValidationError(fmt.Sprintf("secure link %q conflicts with %s on port %d", link.Name, owner, link.Port))
+		}
+		portOwners[link.Port] = fmt.Sprintf("secure link %q", link.Name)
+	}
+
+	for i := 0; i < len(firewallRules); i++ {
+		for port := firewallRules[i].StartPort; port <= firewallRules[i].EndPort; port++ {
+			if owner, exists := portOwners[port]; exists {
+				return breverrors.NewValidationError(fmt.Sprintf("firewall rule %q conflicts with %s on port %d", firewallRules[i].Ports, owner, port))
+			}
+		}
+
+		for j := i + 1; j < len(firewallRules); j++ {
+			if firewallRulesOverlap(firewallRules[i], firewallRules[j]) {
+				return breverrors.NewValidationError(fmt.Sprintf("firewall rule %q conflicts with firewall rule %q", firewallRules[i].Ports, firewallRules[j].Ports))
+			}
+		}
+	}
+
+	return nil
+}
+
+func firewallRulesOverlap(a, b firewallRuleSpec) bool {
+	return !(a.EndPort < b.StartPort || b.EndPort < a.StartPort)
+}
+
+func parsePortRange(raw string) (int, int, error) {
+	trimmed := strings.TrimSpace(raw)
+	if !strings.Contains(trimmed, "-") {
+		port, err := strconv.Atoi(trimmed)
+		if err != nil {
+			return 0, 0, breverrors.NewValidationError(fmt.Sprintf("port %q must be a valid number", raw))
+		}
+		if port < 1 || port > 65535 {
+			return 0, 0, breverrors.NewValidationError(fmt.Sprintf("port %q must be between 1 and 65535", raw))
+		}
+		return port, port, nil
+	}
+
+	parts := strings.Split(trimmed, "-")
+	if len(parts) != 2 {
+		return 0, 0, breverrors.NewValidationError(fmt.Sprintf("port range %q must use the format start-end", raw))
+	}
+
+	start, err := strconv.Atoi(strings.TrimSpace(parts[0]))
+	if err != nil {
+		return 0, 0, breverrors.NewValidationError(fmt.Sprintf("port range %q has an invalid start port", raw))
+	}
+	end, err := strconv.Atoi(strings.TrimSpace(parts[1]))
+	if err != nil {
+		return 0, 0, breverrors.NewValidationError(fmt.Sprintf("port range %q has an invalid end port", raw))
+	}
+	if start < 1 || start > 65535 || end < 1 || end > 65535 {
+		return 0, 0, breverrors.NewValidationError(fmt.Sprintf("port range %q must stay within 1-65535", raw))
+	}
+	if start >= end {
+		return 0, 0, breverrors.NewValidationError(fmt.Sprintf("port range %q must have start < end", raw))
+	}
+
+	return start, end, nil
+}
+
+func resolveDockerCompose(launchableStore LaunchableCmdStore, opts launchableCreateOptions) (*store.DockerCompose, error) {
+	if opts.Mode != "compose" {
+		return nil, nil
+	}
+
+	req := store.ValidateDockerComposeRequest{}
+	build := &store.DockerCompose{
+		JupyterInstall: opts.Jupyter,
+	}
+
+	switch {
+	case opts.ComposeURL != "":
+		err := validateFileURL(opts.ComposeURL)
+		if err != nil {
+			return nil, err
+		}
+		req.FileURL = replaceBlobWithRaw(strings.TrimSpace(opts.ComposeURL))
+		build.FileURL = req.FileURL
+	case opts.ComposeFilePath != "":
+		content, err := os.ReadFile(opts.ComposeFilePath)
+		if err != nil {
+			return nil, breverrors.WrapAndTrace(err)
+		}
+		if strings.TrimSpace(string(content)) == "" {
+			return nil, breverrors.NewValidationError("--compose-file cannot be empty")
+		}
+		req.YamlString = string(content)
+		build.YamlString = req.YamlString
+	case opts.ComposeYAML != "":
+		if strings.TrimSpace(opts.ComposeYAML) == "" {
+			return nil, breverrors.NewValidationError("--compose-yaml cannot be empty")
+		}
+		req.YamlString = opts.ComposeYAML
+		build.YamlString = opts.ComposeYAML
+	}
+
+	_, err := launchableStore.ValidateDockerCompose(req)
+	if err != nil {
+		return nil, breverrors.WrapAndTrace(err)
+	}
+
+	return build, nil
+}
+
+func buildCreateEnvironmentLaunchableRequest(
+	opts launchableCreateOptions,
+	instanceType gpusearch.InstanceType,
+	storageValue string,
+	fileURL string,
+	lifecycleScript string,
+	dockerCompose *store.DockerCompose,
+	secureLinks []secureLinkSpec,
+	firewallRules []firewallRuleSpec,
+) store.CreateEnvironmentLaunchableRequest {
+	createWorkspaceRequest := store.CreateEnvironmentLaunchableWorkspaceRequest{
+		WorkspaceGroupID: instanceType.WorkspaceGroups[0].ID,
+		InstanceType:     instanceType.Type,
+		Storage:          storageValue,
+	}
+
+	if len(firewallRules) > 0 {
+		createWorkspaceRequest.FirewallRules = make([]store.CreateFirewallRule, 0, len(firewallRules))
+		for _, rule := range firewallRules {
+			createWorkspaceRequest.FirewallRules = append(createWorkspaceRequest.FirewallRules, store.CreateFirewallRule{
+				Port:       rule.Ports,
+				AllowedIPs: rule.AllowedIPs,
+			})
+		}
+	}
+
+	buildRequest := store.CreateEnvironmentLaunchableBuildRequest{}
+	if len(secureLinks) > 0 {
+		buildRequest.Ports = make([]store.LaunchablePort, 0, len(secureLinks))
+		for _, link := range secureLinks {
+			var labels map[string]string
+			if link.CTA {
+				labels = map[string]string{
+					"cta-enabled": "true",
+					"cta-value":   defaultString(link.CTALabel, link.Name),
+				}
+			}
+			buildRequest.Ports = append(buildRequest.Ports, store.LaunchablePort{
+				Name:   link.Name,
+				Port:   strconv.Itoa(link.Port),
+				Labels: labels,
+			})
+		}
+	}
+
+	if opts.Mode == "vm" {
+		buildRequest.VMBuild = &store.VMBuild{
+			ForceJupyterInstall: opts.Jupyter,
+		}
+		if lifecycleScript != "" {
+			buildRequest.VMBuild.LifeCycleScriptAttr = &store.LifeCycleScriptAttr{
+				Script: lifecycleScript,
+			}
+		}
+	} else if dockerCompose != nil {
+		buildRequest.DockerCompose = dockerCompose
+	}
+
+	var file *store.LaunchableFile
+	if fileURL != "" {
+		file = &store.LaunchableFile{
+			URL:  fileURL,
+			Path: "./",
+		}
+	}
+
+	return store.CreateEnvironmentLaunchableRequest{
+		Name:                   strings.TrimSpace(opts.Name),
+		Description:            strings.TrimSpace(opts.Description),
+		ViewAccess:             opts.ViewAccess,
+		CreateWorkspaceRequest: createWorkspaceRequest,
+		BuildRequest:           buildRequest,
+		File:                   file,
+	}
+}
+
+func parseFlagAssignments(raw string) (map[string]string, error) {
+	assignments := map[string]string{}
+	for _, part := range strings.Split(raw, ",") {
+		part = strings.TrimSpace(part)
+		if part == "" {
+			continue
+		}
+		kv := strings.SplitN(part, "=", 2)
+		if len(kv) != 2 {
+			return nil, breverrors.NewValidationError(fmt.Sprintf("invalid flag value %q; use comma-separated key=value pairs", raw))
+		}
+		key := strings.TrimSpace(kv[0])
+		value := strings.TrimSpace(kv[1])
+		if key == "" {
+			return nil, breverrors.NewValidationError(fmt.Sprintf("invalid flag value %q; keys cannot be empty", raw))
+		}
+		assignments[key] = value
+	}
+	return assignments, nil
+}
+
+func validateTunnelName(name string) string {
+	if name == "" {
+		return "Name is required"
+	}
+	if len(name) > 63 {
+		return "Name must be 63 characters or fewer"
+	}
+	if !regexp.MustCompile(`^[a-z0-9]`).MatchString(name) {
+		return "Name must start with a lowercase letter or digit"
+	}
+	if !regexp.MustCompile(`^[a-z0-9-]+$`).MatchString(name) {
+		return "Name may only contain lowercase letters, digits, and hyphens"
+	}
+	if !regexp.MustCompile(`[a-z0-9]$`).MatchString(name) {
+		return "Name must end with a lowercase letter or digit"
+	}
+	return ""
+}
+
+func buildLaunchableDeployURL(launchableID string) string {
+	consoleURL := config.GlobalConfig.GetConsoleURL()
+	u, err := url.Parse(consoleURL)
+	if err != nil || u.Scheme == "" || u.Host == "" {
+		return strings.TrimRight(consoleURL, "/") + "/launchable/deploy?launchableID=" + launchableID
+	}
+
+	u.Path = "/launchable/deploy"
+	query := u.Query()
+	query.Set("launchableID", launchableID)
+	u.RawQuery = query.Encode()
+
+	return u.String()
+}
+
+func parseSizeToGiB(raw string) (int, error) {
+	trimmed := strings.TrimSpace(raw)
+	match := sizePattern.FindStringSubmatch(trimmed)
+	if match == nil {
+		return 0, breverrors.NewValidationError(fmt.Sprintf("unsupported size value %q", raw))
+	}
+
+	value, err := strconv.ParseFloat(match[1], 64)
+	if err != nil {
+		return 0, breverrors.WrapAndTrace(err)
+	}
+
+	unit := strings.ToLower(match[2])
+	switch unit {
+	case "gib", "gb":
+		return int(value), nil
+	case "mib", "mb":
+		return int(value / 1024), nil
+	case "tib", "tb":
+		return int(value * 1024), nil
+	case "b":
+		return int(value / (1024 * 1024 * 1024)), nil
+	default:
+		return 0, breverrors.NewValidationError(fmt.Sprintf("unsupported size unit in %q", raw))
+	}
+}
+
+func defaultString(value string, fallback string) string {
+	if strings.TrimSpace(value) == "" {
+		return fallback
+	}
+	return value
+}
diff --git a/pkg/cmd/launchable/create_test.go b/pkg/cmd/launchable/create_test.go
new file mode 100644
index 00000000..7dc13a4b
--- /dev/null
+++ b/pkg/cmd/launchable/create_test.go
@@ -0,0 +1,133 @@
+package launchable
+
+import (
+	"testing"
+
+	"github.com/brevdev/brev-cli/pkg/cmd/gpusearch"
+	"github.com/brevdev/brev-cli/pkg/store"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestValidateCreateOptions(t *testing.T) {
+	t.Run("compose requires exactly one source", func(t *testing.T) {
+		err := validateCreateOptions(launchableCreateOptions{
+			Name:         "demo",
+			ViewAccess:   "public",
+			Mode:         "compose",
+			InstanceType: "g5.xlarge",
+			ComposeURL:   "https://github.com/acme/demo/blob/main/docker-compose.yml",
+			ComposeYAML:  "services: {}",
+		})
+
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "exactly one")
+	})
+
+	t.Run("vm rejects compose sources", func(t *testing.T) {
+		err := validateCreateOptions(launchableCreateOptions{
+			Name:            "demo",
+			ViewAccess:      "public",
+			Mode:            "vm",
+			InstanceType:    "g5.xlarge",
+			ComposeFilePath: "./docker-compose.yml",
+		})
+
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "only valid with --mode compose")
+	})
+}
+
+func TestValidateLifecycleScript(t *testing.T) {
+	err := validateLifecycleScript("echo hello")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "#!/bin/bash")
+
+	err = validateLifecycleScript("#!/bin/bash\necho hello")
+	require.NoError(t, err)
+}
+
+func TestParseSecureLinks(t *testing.T) {
+	links, err := parseSecureLinks([]string{
+		"name=web,port=8080,cta=true,cta-label=Launch",
+		"name=admin,port=3000",
+	})
+	require.NoError(t, err)
+	require.Len(t, links, 2)
+	assert.Equal(t, "web", links[0].Name)
+	assert.True(t, links[0].CTA)
+	assert.Equal(t, "Launch", links[0].CTALabel)
+
+	_, err = parseSecureLinks([]string{
+		"name=bad_name,port=8080",
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "invalid secure link name")
+}
+
+func TestValidatePortConflicts(t *testing.T) {
+	err := validatePortConflicts(
+		[]secureLinkSpec{{Name: "web", Port: 8080}},
+		[]firewallRuleSpec{{Ports: "8000-8100", StartPort: 8000, EndPort: 8100, AllowedIPs: "all"}},
+	)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "conflicts")
+}
+
+func TestResolveStorageValue(t *testing.T) {
+	instance := gpusearch.InstanceType{
+		Type: "g5.xlarge",
+		SupportedStorage: []gpusearch.Storage{
+			{MinSize: "100GiB", MaxSize: "16000GiB"},
+		},
+	}
+
+	value, err := resolveStorageValue(instance, "")
+	require.NoError(t, err)
+	assert.Equal(t, "256", value)
+
+	value, err = resolveStorageValue(instance, "512")
+	require.NoError(t, err)
+	assert.Equal(t, "512", value)
+}
+
+func TestBuildCreateEnvironmentLaunchableRequest(t *testing.T) {
+	req := buildCreateEnvironmentLaunchableRequest(
+		launchableCreateOptions{
+			Name:        "demo",
+			Description: "desc",
+			ViewAccess:  "organization",
+			Mode:        "compose",
+			Jupyter:     false,
+		},
+		gpusearch.InstanceType{
+			Type: "g5.xlarge",
+			WorkspaceGroups: []gpusearch.WorkspaceGroup{
+				{ID: "wg-1"},
+			},
+		},
+		"256",
+		"https://github.com/acme/demo/raw/main/README.md",
+		"",
+		&store.DockerCompose{
+			FileURL:        "https://github.com/acme/demo/raw/main/docker-compose.yml",
+			JupyterInstall: false,
+		},
+		[]secureLinkSpec{
+			{Name: "web", Port: 3000, CTA: true, CTALabel: "Open Web"},
+		},
+		[]firewallRuleSpec{
+			{Ports: "8000-8100", AllowedIPs: "user-ip", StartPort: 8000, EndPort: 8100},
+		},
+	)
+
+	assert.Equal(t, "demo", req.Name)
+	assert.Equal(t, "wg-1", req.CreateWorkspaceRequest.WorkspaceGroupID)
+	assert.Equal(t, "256", req.CreateWorkspaceRequest.Storage)
+	require.NotNil(t, req.BuildRequest.DockerCompose)
+	assert.Equal(t, "https://github.com/acme/demo/raw/main/docker-compose.yml", req.BuildRequest.DockerCompose.FileURL)
+	require.Len(t, req.BuildRequest.Ports, 1)
+	assert.Equal(t, "true", req.BuildRequest.Ports[0].Labels["cta-enabled"])
+	require.NotNil(t, req.File)
+	assert.Equal(t, "./", req.File.Path)
+}
diff --git a/pkg/cmd/launchable/launchable.go b/pkg/cmd/launchable/launchable.go
new file mode 100644
index 00000000..43623f03
--- /dev/null
+++ b/pkg/cmd/launchable/launchable.go
@@ -0,0 +1,29 @@
+package launchable
+
+import (
+	"github.com/brevdev/brev-cli/pkg/cmd/gpusearch"
+	"github.com/brevdev/brev-cli/pkg/entity"
+	"github.com/brevdev/brev-cli/pkg/store"
+	"github.com/brevdev/brev-cli/pkg/terminal"
+	"github.com/spf13/cobra"
+)
+
+type LaunchableCmdStore interface {
+	GetActiveOrganizationOrDefault() (*entity.Organization, error)
+	GetAllInstanceTypesWithWorkspaceGroups(orgID string) (*gpusearch.AllInstanceTypesResponse, error)
+	CreateEnvironmentLaunchable(organizationID string, req store.CreateEnvironmentLaunchableRequest) (*store.CreateLaunchableResponse, error)
+	ValidateDockerCompose(req store.ValidateDockerComposeRequest) (*store.ValidateDockerComposeResponse, error)
+}
+
+func NewCmdLaunchable(t *terminal.Terminal, store LaunchableCmdStore) *cobra.Command {
+	cmd := &cobra.Command{
+		Annotations: map[string]string{"organization": ""},
+		Use:         "launchable",
+		Short:       "Launchable commands",
+		Long:        "Create and manage launchables.",
+	}
+
+	cmd.AddCommand(NewCmdLaunchableCreate(t, store))
+
+	return cmd
+}
diff --git a/pkg/store/launchable.go b/pkg/store/launchable.go
new file mode 100644
index 00000000..ad4b0043
--- /dev/null
+++ b/pkg/store/launchable.go
@@ -0,0 +1,92 @@
+package store
+
+import (
+	"fmt"
+
+	breverrors "github.com/brevdev/brev-cli/pkg/errors"
+)
+
+const (
+	createEnvironmentLaunchablePathPattern = "api/organizations/%s/v2/launchables"
+	createEnvironmentLaunchablePath        = fmt.Sprintf(createEnvironmentLaunchablePathPattern, fmt.Sprintf("{%s}", orgIDParamName))
+	validateDockerComposePath              = "api/file-validation/docker-compose"
+)
+
+type CreateLaunchableResponse struct {
+	ID string `json:"id"`
+}
+
+type CreateFirewallRule struct {
+	Port       string   `json:"port"`
+	AllowedIPs string   `json:"allowedIPs"`
+	ClientIPs  []string `json:"clientIPs,omitempty"`
+}
+
+type CreateEnvironmentLaunchableWorkspaceRequest struct {
+	WorkspaceGroupID string               `json:"workspaceGroupId"`
+	InstanceType     string               `json:"instanceType"`
+	Location         string               `json:"location,omitempty"`
+	Region           string               `json:"region,omitempty"`
+	SubLocation      string               `json:"subLocation,omitempty"`
+	Storage          string               `json:"storage,omitempty"`
+	FirewallRules    []CreateFirewallRule `json:"firewallRules,omitempty"`
+	ImageID          string               `json:"imageId,omitempty"`
+}
+
+type CreateEnvironmentLaunchableBuildRequest struct {
+	VMBuild        *VMBuild         `json:"vmBuild,omitempty"`
+	ContainerBuild *CustomContainer `json:"containerBuild,omitempty"`
+	DockerCompose  *DockerCompose   `json:"dockerCompose,omitempty"`
+	Ports          []LaunchablePort `json:"ports,omitempty"`
+}
+
+type CreateEnvironmentLaunchableRequest struct {
+	Name                   string                                      `json:"name"`
+	Description            string                                      `json:"description"`
+	ViewAccess             string                                      `json:"viewAccess"`
+	CreateWorkspaceRequest CreateEnvironmentLaunchableWorkspaceRequest `json:"createWorkspaceRequest"`
+	BuildRequest           CreateEnvironmentLaunchableBuildRequest     `json:"buildRequest"`
+	File                   *LaunchableFile                             `json:"file,omitempty"`
+}
+
+type ValidateDockerComposeRequest struct {
+	FileURL    string `json:"fileUrl,omitempty"`
+	YamlString string `json:"yamlString,omitempty"`
+}
+
+type ValidateDockerComposeResponse map[string]interface{}
+
+func (s AuthHTTPStore) CreateEnvironmentLaunchable(organizationID string, req CreateEnvironmentLaunchableRequest) (*CreateLaunchableResponse, error) {
+	var result CreateLaunchableResponse
+	res, err := s.authHTTPClient.restyClient.R().
+		SetHeader("Content-Type", "application/json").
+		SetPathParam(orgIDParamName, organizationID).
+		SetBody(req).
+		SetResult(&result).
+		Post(createEnvironmentLaunchablePath)
+	if err != nil {
+		return nil, breverrors.WrapAndTrace(err)
+	}
+	if res.IsError() {
+		return nil, NewHTTPResponseError(res)
+	}
+
+	return &result, nil
+}
+
+func (s AuthHTTPStore) ValidateDockerCompose(req ValidateDockerComposeRequest) (*ValidateDockerComposeResponse, error) {
+	result := ValidateDockerComposeResponse{}
+	res, err := s.authHTTPClient.restyClient.R().
+		SetHeader("Content-Type", "application/json").
+		SetBody(req).
+		SetResult(&result).
+		Post(validateDockerComposePath)
+	if err != nil {
+		return nil, breverrors.WrapAndTrace(err)
+	}
+	if res.IsError() {
+		return nil, NewHTTPResponseError(res)
+	}
+
+	return &result, nil
+}

From 3aca6d301303545b4eb25b281a966d662449cda3 Mon Sep 17 00:00:00 2001
From: Tyler Fong <tyler@brev.dev>
Date: Fri, 17 Apr 2026 00:02:03 +0000
Subject: [PATCH 2/5] fixed build error unit tests

---
 pkg/store/launchable.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pkg/store/launchable.go b/pkg/store/launchable.go
index ad4b0043..166b61b5 100644
--- a/pkg/store/launchable.go
+++ b/pkg/store/launchable.go
@@ -6,7 +6,7 @@ import (
 	breverrors "github.com/brevdev/brev-cli/pkg/errors"
 )
 
-const (
+var (
 	createEnvironmentLaunchablePathPattern = "api/organizations/%s/v2/launchables"
 	createEnvironmentLaunchablePath        = fmt.Sprintf(createEnvironmentLaunchablePathPattern, fmt.Sprintf("{%s}", orgIDParamName))
 	validateDockerComposePath              = "api/file-validation/docker-compose"

From bee06215458fec9ffd8ffe359c7afdde2125fd6f Mon Sep 17 00:00:00 2001
From: Tyler Fong <tylerf@nvidia.com>
Date: Fri, 17 Apr 2026 13:32:28 -0700
Subject: [PATCH 3/5] added doc.md

---
 pkg/cmd/launchable/doc.md | 744 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 744 insertions(+)
 create mode 100644 pkg/cmd/launchable/doc.md

diff --git a/pkg/cmd/launchable/doc.md b/pkg/cmd/launchable/doc.md
new file mode 100644
index 00000000..e785ce50
--- /dev/null
+++ b/pkg/cmd/launchable/doc.md
@@ -0,0 +1,744 @@
+# `brev launchable create`
+
+Create a Brev launchable from the CLI using either:
+
+- VM mode
+- Docker Compose mode
+
+This command is intended to mirror the current launchable create flow in the console for the supported scope in the CLI.
+
+## Synopsis
+
+```bash
+brev launchable create [name] [flags]
+```
+
+The launchable name can be passed either:
+
+- as the positional argument: `brev launchable create my-launchable ...`
+- or with `--name`: `brev launchable create --name my-launchable ...`
+
+## What This Command Creates
+
+A launchable is a reusable environment definition that captures:
+
+- the compute shape
+- the build mode
+- the optional preload file/repo URL
+- the network access model
+- the launchable visibility
+
+When a launchable is created, the CLI sends a request containing:
+
+- `name`
+- `description`
+- `viewAccess`
+- `createWorkspaceRequest`
+- `buildRequest`
+- optional `file`
+
+## Supported Build Modes
+
+### `vm`
+
+VM mode creates a launchable backed by a VM build.
+
+Use VM mode when you want:
+
+- host-based Jupyter installation
+- a lifecycle/setup script
+- simple launchables that do not require Docker Compose
+
+### `compose`
+
+Compose mode creates a launchable backed by Docker Compose.
+
+Use Compose mode when you want:
+
+- a multi-service environment
+- a compose file hosted remotely
+- a local compose file
+- inline compose YAML
+
+The CLI validates the compose definition before sending the create request.
+
+## Current CLI Scope
+
+The current CLI implementation supports:
+
+- `vm`
+- `compose`
+
+The current CLI implementation does not support:
+
+- featured container / verb-based launchables
+- raw custom container build mode
+- private registry flags
+- API-only location and image overrides
+
+## Required Inputs
+
+At minimum, you must provide:
+
+- a launchable name
+- `--instance-type`
+- `--mode`
+
+For `compose` mode you must also provide exactly one compose source:
+
+- `--compose-url`
+- `--compose-file`
+- `--compose-yaml`
+
+## Full Flag Reference
+
+### Core Flags
+
+#### `--name`, `-n`
+
+Explicit launchable name.
+
+```bash
+brev launchable create --name my-launchable --mode vm --instance-type n2-standard-4
+```
+
+#### Positional name
+
+Equivalent to `--name`.
+
+```bash
+brev launchable create my-launchable --mode vm --instance-type n2-standard-4
+```
+
+#### `--description`
+
+Optional human-readable description stored on the launchable.
+
+```bash
+--description "Stable VM launchable for onboarding"
+```
+
+#### `--view-access`
+
+Controls who can access the launchable.
+
+Allowed values:
+
+- `public`
+- `organization`
+- `published`
+
+Default:
+
+```bash
+--view-access public
+```
+
+Examples:
+
+```bash
+--view-access organization
+--view-access published
+```
+
+#### `--mode`, `-m`
+
+Build mode.
+
+Allowed values:
+
+- `vm`
+- `compose`
+
+Default:
+
+```bash
+--mode vm
+```
+
+#### `--instance-type`, `-t`
+
+Required. The exact instance type to attach to the launchable.
+
+Examples:
+
+```bash
+--instance-type n2-standard-4
+--instance-type g5.xlarge
+```
+
+#### `--storage`
+
+Optional root disk size in GiB.
+
+Behavior:
+
+- If the selected instance type supports flexible storage, this value is sent to the API.
+- If the selected instance type has fixed storage, the CLI rejects `--storage`.
+- If flexible storage is supported and `--storage` is omitted, the CLI defaults to `256` GiB, clamped to the instance type's min/max storage range.
+
+Examples:
+
+```bash
+--storage 256
+--storage 512
+```
+
+### File Source Flag
+
+#### `--file-url`
+
+Optional public file or repo URL to preload into the launchable.
+
+Typical uses:
+
+- GitHub repo URL
+- GitLab repo URL
+- notebook URL
+- markdown URL
+
+Normalization:
+
+- GitHub `/blob/` URLs are converted to `/raw/`
+- GitLab `/-/blob/` URLs are converted to `/-/raw/`
+
+Rejected URL patterns:
+
+- trailing slash URLs
+- GitHub directory tree URLs
+- GitLab directory tree URLs
+
+Example:
+
+```bash
+--file-url https://github.com/acme/project
+--file-url https://github.com/acme/project/blob/main/README.md
+```
+
+## VM Mode Flags
+
+These flags are valid only when `--mode vm`.
+
+### `--jupyter`
+
+Controls host-side Jupyter installation.
+
+Default:
+
+```bash
+--jupyter=true
+```
+
+Example:
+
+```bash
+--jupyter=false
+```
+
+### `--lifecycle-script`
+
+Inline lifecycle/setup script.
+
+The script:
+
+- must start with `#!/bin/bash`
+- must be at most 16 KiB
+
+Example:
+
+```bash
+--lifecycle-script '#!/bin/bash
+echo hello
+apt-get update'
+```
+
+For anything more than a few lines, prefer `--lifecycle-script-file`.
+
+### `--lifecycle-script-file`
+
+Path to a local lifecycle/setup script file.
+
+This is mutually exclusive with `--lifecycle-script`.
+
+Example:
+
+```bash
+--lifecycle-script-file ./scripts/setup.sh
+```
+
+## Compose Mode Flags
+
+These flags are valid only when `--mode compose`.
+
+Exactly one compose source is required.
+
+### `--compose-url`
+
+Public remote Docker Compose URL.
+
+Blob URLs are normalized to raw URLs before validation and create.
+
+Example:
+
+```bash
+--compose-url https://github.com/acme/project/blob/main/docker-compose.yml
+```
+
+### `--compose-file`
+
+Path to a local Docker Compose file.
+
+Example:
+
+```bash
+--compose-file ./docker-compose.yml
+```
+
+### `--compose-yaml`
+
+Inline Docker Compose YAML.
+
+Best for short examples. For real-world compose content, prefer `--compose-file`.
+
+Example:
+
+```bash
+--compose-yaml $'version: "3"\nservices:\n  web:\n    image: nginx\n    ports:\n      - "8080:80"'
+```
+
+### `--jupyter`
+
+Also applies in compose mode.
+
+In compose mode this controls host-side Jupyter installation in the launchable build request.
+
+## Network Flags
+
+The CLI exposes two separate networking concepts:
+
+- secure links
+- firewall rules
+
+Secure links are user-facing exposed entry points stored in `buildRequest.ports`.
+
+Firewall rules are lower-level ingress rules stored in `createWorkspaceRequest.firewallRules`.
+
+### `--secure-link`
+
+Repeatable flag.
+
+Format:
+
+```text
+name=<name>,port=<port>[,cta=true|false][,cta-label=<label>]
+```
+
+Fields:
+
+- `name` is required
+- `port` is required
+- `cta` is optional
+- `cta-label` is optional and only valid when `cta=true`
+
+Examples:
+
+```bash
+--secure-link name=web,port=3000
+--secure-link name=notebook,port=8888,cta=true
+--secure-link name=api,port=8080,cta=true,cta-label=OpenAPI
+```
+
+Validation:
+
+- secure link names must be lowercase DNS-label style names
+- only lowercase letters, digits, and hyphens are allowed
+- names must start and end with a lowercase letter or digit
+- max length is 63 characters
+- ports must be a single port, not a range
+- ports must be between `1` and `65535`
+- duplicate secure link names are rejected
+- at most 2 secure links may use `cta=true`
+
+Example of a valid name:
+
+```text
+web
+demo-app
+jupyter1
+```
+
+Example of invalid names:
+
+```text
+Web
+demo_app
+-demo
+demo-
+```
+
+### `--firewall-rule`
+
+Repeatable flag.
+
+Format:
+
+```text
+ports=<port|start-end>[,allowed-ips=all|user-ip]
+```
+
+Fields:
+
+- `ports` is required
+- `allowed-ips` is optional
+
+Default:
+
+```text
+allowed-ips=all
+```
+
+Examples:
+
+```bash
+--firewall-rule ports=8080
+--firewall-rule ports=8000-8100
+--firewall-rule ports=8000-8100,allowed-ips=user-ip
+```
+
+Validation:
+
+- single ports must be between `1` and `65535`
+- ranges must use `start-end`
+- ranges must satisfy `start < end`
+- only `all` and `user-ip` are currently accepted
+- firewall rules cannot overlap each other
+- firewall rules cannot overlap secure-link ports
+
+## Dry Run
+
+### `--dry-run`
+
+Prints the final request JSON and exits without creating anything.
+
+This is the best way to verify:
+
+- which workspace group was selected
+- whether storage was included
+- how URLs were normalized
+- how ports and firewall rules were serialized
+
+Example:
+
+```bash
+brev launchable create demo \
+  --mode vm \
+  --instance-type n2-standard-4 \
+  --dry-run
+```
+
+## Validation Rules and Mutual Exclusivity
+
+The CLI intentionally catches several issues before sending the API request.
+
+### Name and Core Input Validation
+
+- launchable name is required
+- instance type is required
+- mode must be `vm` or `compose`
+- view access must be `public`, `organization`, or `published`
+
+### VM vs Compose Exclusivity
+
+When `--mode vm`:
+
+- `--compose-url` is invalid
+- `--compose-file` is invalid
+- `--compose-yaml` is invalid
+
+When `--mode compose`:
+
+- `--lifecycle-script` is invalid
+- `--lifecycle-script-file` is invalid
+- exactly one compose source is required
+
+### Lifecycle Script Validation
+
+- empty script is allowed
+- non-empty scripts must start with `#!/bin/bash`
+- max size is 16 KiB
+- inline and file-based script flags are mutually exclusive
+
+### Compose Validation
+
+Before creation, the CLI sends the compose source to the Docker Compose validation API.
+
+That means:
+
+- malformed compose definitions fail early
+- invalid remote compose URLs fail before create
+- local compose files are read and validated before create
+
+### Port Conflict Validation
+
+The CLI rejects:
+
+- secure-link port conflicts with other secure links
+- secure-link port conflicts with firewall rules
+- firewall rule overlaps with firewall rules
+
+## Examples
+
+## Example 1: Minimal VM Launchable
+
+```bash
+brev launchable create my-vm \
+  --mode vm \
+  --instance-type n2-standard-4
+```
+
+What this does:
+
+- creates a VM launchable
+- uses default `public` visibility
+- enables Jupyter by default
+- uses default storage behavior for the instance type
+- sends no preload file URL
+- sends no secure links
+- sends no firewall rules
+
+## Example 2: VM Launchable With Script and Secure Link
+
+```bash
+brev launchable create ds-notebook \
+  --mode vm \
+  --instance-type n2-standard-4 \
+  --description "Notebook-based onboarding launchable" \
+  --lifecycle-script-file ./scripts/bootstrap.sh \
+  --secure-link name=notebook,port=8888,cta=true,cta-label=OpenNotebook
+```
+
+What this does:
+
+- installs Jupyter on the host
+- attaches a lifecycle script
+- exposes a user-facing secure link named `notebook`
+- makes that secure link a CTA entry point
+
+## Example 3: VM Launchable With Repo Preload and Firewall Rules
+
+```bash
+brev launchable create training-vm \
+  --mode vm \
+  --instance-type g5.xlarge \
+  --storage 512 \
+  --file-url https://github.com/acme/training-project \
+  --secure-link name=jupyter,port=8888,cta=true \
+  --firewall-rule ports=8000-8100,allowed-ips=user-ip
+```
+
+What this does:
+
+- creates a GPU-backed VM launchable
+- sets storage to 512 GiB if the instance type supports flexible storage
+- preloads the repo into the workspace
+- exposes Jupyter as a secure link
+- opens a user-IP-scoped firewall range
+
+## Example 4: Compose Launchable From Remote URL
+
+```bash
+brev launchable create compose-demo \
+  --mode compose \
+  --instance-type g5.xlarge \
+  --compose-url https://github.com/acme/project/blob/main/docker-compose.yml \
+  --secure-link name=web,port=3000,cta=true,cta-label=LaunchApp
+```
+
+What this does:
+
+- converts the GitHub blob URL to a raw URL
+- validates the compose document before create
+- creates a compose-backed launchable
+- exposes port `3000` as the main user-facing link
+
+## Example 5: Compose Launchable From Local File
+
+```bash
+brev launchable create local-compose \
+  --mode compose \
+  --instance-type g5.xlarge \
+  --compose-file ./docker-compose.yml \
+  --file-url https://github.com/acme/project \
+  --secure-link name=ui,port=8080,cta=true \
+  --secure-link name=api,port=8000
+```
+
+## Example 6: Compose Launchable From Inline YAML
+
+```bash
+brev launchable create inline-compose \
+  --mode compose \
+  --instance-type g5.xlarge \
+  --compose-yaml $'version: "3"\nservices:\n  web:\n    image: nginx\n    ports:\n      - "8080:80"' \
+  --secure-link name=web,port=8080,cta=true
+```
+
+## Example 7: Inspect Request Without Creating
+
+```bash
+brev launchable create dry-run-demo \
+  --mode compose \
+  --instance-type g5.xlarge \
+  --compose-file ./docker-compose.yml \
+  --secure-link name=web,port=3000,cta=true \
+  --firewall-rule ports=8000-8010,allowed-ips=user-ip \
+  --dry-run
+```
+
+## Request Shape
+
+The CLI builds a request that looks conceptually like this:
+
+```json
+{
+  "name": "demo",
+  "description": "Example launchable",
+  "viewAccess": "public",
+  "createWorkspaceRequest": {
+    "workspaceGroupId": "wg-123",
+    "instanceType": "g5.xlarge",
+    "storage": "256",
+    "firewallRules": [
+      {
+        "port": "8000-8100",
+        "allowedIPs": "user-ip"
+      }
+    ]
+  },
+  "buildRequest": {
+    "dockerCompose": {
+      "fileUrl": "https://github.com/acme/project/raw/main/docker-compose.yml",
+      "jupyterInstall": true
+    },
+    "ports": [
+      {
+        "name": "web",
+        "port": "3000",
+        "labels": {
+          "cta-enabled": "true",
+          "cta-value": "LaunchApp"
+        }
+      }
+    ]
+  },
+  "file": {
+    "url": "https://github.com/acme/project",
+    "path": "./"
+  }
+}
+```
+
+## Successful Output
+
+On success, the CLI prints:
+
+- the created launchable ID
+- a deploy URL based on the configured console URL
+
+Conceptually:
+
+```text
+Created launchable "demo" (env-abc123)
+Deploy URL: https://brev.nvidia.com/launchable/deploy?launchableID=env-abc123
+```
+
+## Troubleshooting
+
+### `--storage` is rejected
+
+That means the instance type is exposing fixed storage in the current API response. Omit `--storage`.
+
+### Compose create fails before launchable creation
+
+That usually means compose validation failed. Check:
+
+- YAML syntax
+- remote URL accessibility
+- whether the URL points to a file instead of a directory
+
+### Secure link name is rejected
+
+Rename it to a lowercase DNS-label style value such as:
+
+```text
+web
+demo-app
+jupyter
+```
+
+### Firewall rule conflicts
+
+The CLI checks secure-link ports and firewall rule ranges together. Make sure:
+
+- no secure-link port is duplicated
+- no secure-link port falls inside a firewall range
+- firewall ranges do not overlap each other
+
+## Recommended Usage Patterns
+
+### Prefer `--compose-file` over `--compose-yaml`
+
+Use inline YAML only for quick tests. For anything real, a file is easier to maintain and quote safely.
+
+### Use `--dry-run` before large or shared launchables
+
+This is the fastest way to verify the final request.
+
+### Keep CTA links intentional
+
+Use `cta=true` only on the 1-2 main entry points you want users to click first.
+
+### Use `--file-url` for preload content, not for compose source
+
+Use:
+
+- `--file-url` for repo/notebook/markdown preload content
+- `--compose-*` for the actual Docker Compose definition
+
+## Quick Reference
+
+### Minimal VM
+
+```bash
+brev launchable create demo --mode vm --instance-type n2-standard-4
+```
+
+### VM With Script
+
+```bash
+brev launchable create demo --mode vm --instance-type n2-standard-4 --lifecycle-script-file ./setup.sh
+```
+
+### Compose From File
+
+```bash
+brev launchable create demo --mode compose --instance-type g5.xlarge --compose-file ./docker-compose.yml
+```
+
+### With Secure Link
+
+```bash
+brev launchable create demo --mode vm --instance-type n2-standard-4 --secure-link name=web,port=8080,cta=true
+```
+
+### With Firewall Rule
+
+```bash
+brev launchable create demo --mode vm --instance-type n2-standard-4 --firewall-rule ports=8000-8100,allowed-ips=user-ip
+```
+
+### Preview Request
+
+```bash
+brev launchable create demo --mode vm --instance-type n2-standard-4 --dry-run
+```

From d4fdd8767cf2509ce5ce0b0ae94a734c540df415 Mon Sep 17 00:00:00 2001
From: Tyler Fong <tylerf@nvidia.com>
Date: Fri, 17 Apr 2026 13:51:04 -0700
Subject: [PATCH 4/5] fixed pr comments

---
 pkg/cmd/launchable/create.go      | 144 +++++++++++++++++++++---------
 pkg/cmd/launchable/create_test.go |  19 ++++
 2 files changed, 119 insertions(+), 44 deletions(-)

diff --git a/pkg/cmd/launchable/create.go b/pkg/cmd/launchable/create.go
index 275bc964..16621e96 100644
--- a/pkg/cmd/launchable/create.go
+++ b/pkg/cmd/launchable/create.go
@@ -330,6 +330,14 @@ func resolveLifecycleScript(opts launchableCreateOptions) (string, error) {
 	var script string
 	switch {
 	case opts.LifecycleFilePath != "":
+		info, err := os.Stat(opts.LifecycleFilePath)
+		if err != nil {
+			return "", breverrors.WrapAndTrace(err)
+		}
+		if info.Size() > int64(maxLifecycleScriptBytes) {
+			return "", breverrors.NewValidationError("--lifecycle-script exceeds the 16 KiB limit")
+		}
+
 		content, err := os.ReadFile(opts.LifecycleFilePath)
 		if err != nil {
 			return "", breverrors.WrapAndTrace(err)
@@ -404,58 +412,20 @@ func parseSecureLinks(rawLinks []string) ([]secureLinkSpec, error) {
 	ctaCount := 0
 
 	for _, raw := range rawLinks {
-		values, err := parseFlagAssignments(raw)
+		link, err := parseSecureLink(raw)
 		if err != nil {
 			return nil, err
 		}
-
-		name := strings.TrimSpace(values["name"])
-		if name == "" {
-			return nil, breverrors.NewValidationError("each --secure-link must include name=<value>")
-		}
-		if msg := validateTunnelName(name); msg != "" {
-			return nil, breverrors.NewValidationError(fmt.Sprintf("invalid secure link name %q: %s", name, msg))
-		}
-		if _, exists := nameSet[name]; exists {
-			return nil, breverrors.NewValidationError(fmt.Sprintf("duplicate secure link name %q", name))
-		}
-		nameSet[name] = struct{}{}
-
-		portText := strings.TrimSpace(values["port"])
-		if portText == "" {
-			return nil, breverrors.NewValidationError(fmt.Sprintf("secure link %q is missing port=<value>", name))
-		}
-		if strings.Contains(portText, "-") {
-			return nil, breverrors.NewValidationError(fmt.Sprintf("secure link %q must use a single port, not a port range", name))
+		if _, exists := nameSet[link.Name]; exists {
+			return nil, breverrors.NewValidationError(fmt.Sprintf("duplicate secure link name %q", link.Name))
 		}
 
-		port, err := strconv.Atoi(portText)
-		if err != nil || port < 1 || port > 65535 {
-			return nil, breverrors.NewValidationError(fmt.Sprintf("secure link %q must use a port between 1 and 65535", name))
-		}
-
-		cta := false
-		if rawCTA, ok := values["cta"]; ok && strings.TrimSpace(rawCTA) != "" {
-			cta, err = strconv.ParseBool(strings.TrimSpace(rawCTA))
-			if err != nil {
-				return nil, breverrors.NewValidationError(fmt.Sprintf("secure link %q has invalid cta value %q; use true or false", name, rawCTA))
-			}
-		}
-
-		ctaLabel := strings.TrimSpace(values["cta-label"])
-		if ctaLabel != "" && !cta {
-			return nil, breverrors.NewValidationError(fmt.Sprintf("secure link %q cannot set cta-label without cta=true", name))
-		}
-		if cta {
+		nameSet[link.Name] = struct{}{}
+		if link.CTA {
 			ctaCount++
 		}
 
-		links = append(links, secureLinkSpec{
-			Name:     name,
-			Port:     port,
-			CTA:      cta,
-			CTALabel: ctaLabel,
-		})
+		links = append(links, link)
 	}
 
 	if ctaCount > maxCTAServiceCount {
@@ -465,6 +435,92 @@ func parseSecureLinks(rawLinks []string) ([]secureLinkSpec, error) {
 	return links, nil
 }
 
+func parseSecureLink(raw string) (secureLinkSpec, error) {
+	values, err := parseFlagAssignments(raw)
+	if err != nil {
+		return secureLinkSpec{}, err
+	}
+
+	name, err := parseSecureLinkName(values)
+	if err != nil {
+		return secureLinkSpec{}, err
+	}
+
+	port, err := parseSecureLinkPort(name, values)
+	if err != nil {
+		return secureLinkSpec{}, err
+	}
+
+	cta, err := parseSecureLinkCTA(name, values)
+	if err != nil {
+		return secureLinkSpec{}, err
+	}
+
+	ctaLabel, err := parseSecureLinkCTALabel(name, cta, values)
+	if err != nil {
+		return secureLinkSpec{}, err
+	}
+
+	return secureLinkSpec{
+		Name:     name,
+		Port:     port,
+		CTA:      cta,
+		CTALabel: ctaLabel,
+	}, nil
+}
+
+func parseSecureLinkName(values map[string]string) (string, error) {
+	name := strings.TrimSpace(values["name"])
+	if name == "" {
+		return "", breverrors.NewValidationError("each --secure-link must include name=<value>")
+	}
+	if msg := validateTunnelName(name); msg != "" {
+		return "", breverrors.NewValidationError(fmt.Sprintf("invalid secure link name %q: %s", name, msg))
+	}
+
+	return name, nil
+}
+
+func parseSecureLinkPort(name string, values map[string]string) (int, error) {
+	portText := strings.TrimSpace(values["port"])
+	if portText == "" {
+		return 0, breverrors.NewValidationError(fmt.Sprintf("secure link %q is missing port=<value>", name))
+	}
+	if strings.Contains(portText, "-") {
+		return 0, breverrors.NewValidationError(fmt.Sprintf("secure link %q must use a single port, not a port range", name))
+	}
+
+	port, err := strconv.Atoi(portText)
+	if err != nil || port < 1 || port > 65535 {
+		return 0, breverrors.NewValidationError(fmt.Sprintf("secure link %q must use a port between 1 and 65535", name))
+	}
+
+	return port, nil
+}
+
+func parseSecureLinkCTA(name string, values map[string]string) (bool, error) {
+	rawCTA, ok := values["cta"]
+	if !ok || strings.TrimSpace(rawCTA) == "" {
+		return false, nil
+	}
+
+	cta, err := strconv.ParseBool(strings.TrimSpace(rawCTA))
+	if err != nil {
+		return false, breverrors.NewValidationError(fmt.Sprintf("secure link %q has invalid cta value %q; use true or false", name, rawCTA))
+	}
+
+	return cta, nil
+}
+
+func parseSecureLinkCTALabel(name string, cta bool, values map[string]string) (string, error) {
+	ctaLabel := strings.TrimSpace(values["cta-label"])
+	if ctaLabel != "" && !cta {
+		return "", breverrors.NewValidationError(fmt.Sprintf("secure link %q cannot set cta-label without cta=true", name))
+	}
+
+	return ctaLabel, nil
+}
+
 func parseFirewallRules(rawRules []string) ([]firewallRuleSpec, error) {
 	if len(rawRules) == 0 {
 		return nil, nil
diff --git a/pkg/cmd/launchable/create_test.go b/pkg/cmd/launchable/create_test.go
index 7dc13a4b..13602dff 100644
--- a/pkg/cmd/launchable/create_test.go
+++ b/pkg/cmd/launchable/create_test.go
@@ -1,6 +1,9 @@
 package launchable
 
 import (
+	"os"
+	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/brevdev/brev-cli/pkg/cmd/gpusearch"
@@ -47,6 +50,22 @@ func TestValidateLifecycleScript(t *testing.T) {
 	require.NoError(t, err)
 }
 
+func TestResolveLifecycleScriptRejectsOversizedFile(t *testing.T) {
+	tempDir := t.TempDir()
+	scriptPath := filepath.Join(tempDir, "setup.sh")
+	content := "#!/bin/bash\n" + strings.Repeat("a", maxLifecycleScriptBytes)
+
+	err := os.WriteFile(scriptPath, []byte(content), 0o644)
+	require.NoError(t, err)
+
+	_, err = resolveLifecycleScript(launchableCreateOptions{
+		Mode:              "vm",
+		LifecycleFilePath: scriptPath,
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "16 KiB")
+}
+
 func TestParseSecureLinks(t *testing.T) {
 	links, err := parseSecureLinks([]string{
 		"name=web,port=8080,cta=true,cta-label=Launch",

From 11b1221ddf0c0405c50f6cdc699f6e0762987d70 Mon Sep 17 00:00:00 2001
From: Tyler Fong <tylerf@nvidia.com>
Date: Fri, 17 Apr 2026 14:24:13 -0700
Subject: [PATCH 5/5] fixed linting

---
 pkg/cmd/launchable/create.go | 165 +++++++++++++++++++++++++----------
 pkg/cmd/launchable/doc.md    |   4 +-
 2 files changed, 120 insertions(+), 49 deletions(-)

diff --git a/pkg/cmd/launchable/create.go b/pkg/cmd/launchable/create.go
index 16621e96..41392919 100644
--- a/pkg/cmd/launchable/create.go
+++ b/pkg/cmd/launchable/create.go
@@ -19,7 +19,7 @@ import (
 )
 
 const (
-	defaultLaunchableViewAccess = "public"
+	defaultLaunchableViewAccess = "organization"
 	defaultLaunchableMode       = "vm"
 	defaultFlexibleStorageGiB   = 256
 	maxLifecycleScriptBytes     = 16 * 1024
@@ -271,57 +271,102 @@ func getSelectedInstanceType(allInstanceTypes *gpusearch.AllInstanceTypesRespons
 }
 
 func resolveStorageValue(instanceType gpusearch.InstanceType, requested string) (string, error) {
+	requested = strings.TrimSpace(requested)
+
 	if len(instanceType.SupportedStorage) == 0 {
-		if requested != "" {
-			return "", breverrors.NewValidationError(fmt.Sprintf("instance type %q does not expose configurable storage; omit --storage", instanceType.Type))
-		}
-		return "", nil
+		return resolveStorageWithoutSupportedStorage(instanceType.Type, requested)
 	}
 
 	storage := instanceType.SupportedStorage[0]
 	if storage.MinSize != "" && storage.MaxSize != "" {
-		minGiB, err := parseSizeToGiB(storage.MinSize)
-		if err != nil {
-			return "", err
-		}
-		maxGiB, err := parseSizeToGiB(storage.MaxSize)
-		if err != nil {
-			return "", err
-		}
+		return resolveFlexibleStorageValue(instanceType.Type, storage, requested)
+	}
 
-		value := strings.TrimSpace(requested)
-		if value == "" {
-			defaultGiB := defaultFlexibleStorageGiB
-			if minGiB > 0 && defaultGiB < minGiB {
-				defaultGiB = minGiB
-			}
-			if maxGiB > 0 && defaultGiB > maxGiB {
-				defaultGiB = maxGiB
-			}
-			value = strconv.Itoa(defaultGiB)
-		}
+	return resolveFixedStorageValue(instanceType.Type, requested)
+}
 
-		sizeGiB, err := strconv.Atoi(value)
-		if err != nil || sizeGiB <= 0 {
-			return "", breverrors.NewValidationError("--storage must be a positive integer number of GiB")
-		}
-		if minGiB > 0 && sizeGiB < minGiB {
-			return "", breverrors.NewValidationError(fmt.Sprintf("--storage must be at least %d GiB for instance type %q", minGiB, instanceType.Type))
-		}
-		if maxGiB > 0 && sizeGiB > maxGiB {
-			return "", breverrors.NewValidationError(fmt.Sprintf("--storage must be at most %d GiB for instance type %q", maxGiB, instanceType.Type))
-		}
+func resolveStorageWithoutSupportedStorage(instanceType string, requested string) (string, error) {
+	if requested != "" {
+		return "", breverrors.NewValidationError(fmt.Sprintf("instance type %q does not expose configurable storage; omit --storage", instanceType))
+	}
 
-		return strconv.Itoa(sizeGiB), nil
+	return "", nil
+}
+
+func resolveFlexibleStorageValue(instanceType string, storage gpusearch.Storage, requested string) (string, error) {
+	minGiB, maxGiB, err := parseFlexibleStorageBounds(storage)
+	if err != nil {
+		return "", err
+	}
+
+	if requested == "" {
+		return strconv.Itoa(clampDefaultFlexibleStorage(minGiB, maxGiB)), nil
+	}
+
+	sizeGiB, err := parseRequestedStorageGiB(requested)
+	if err != nil {
+		return "", err
+	}
+	if err := validateFlexibleStorageBounds(instanceType, sizeGiB, minGiB, maxGiB); err != nil {
+		return "", err
 	}
 
+	return strconv.Itoa(sizeGiB), nil
+}
+
+func resolveFixedStorageValue(instanceType string, requested string) (string, error) {
 	if requested != "" {
-		return "", breverrors.NewValidationError(fmt.Sprintf("instance type %q uses fixed storage; omit --storage", instanceType.Type))
+		return "", breverrors.NewValidationError(fmt.Sprintf("instance type %q uses fixed storage; omit --storage", instanceType))
 	}
 
 	return "", nil
 }
 
+func parseFlexibleStorageBounds(storage gpusearch.Storage) (int, int, error) {
+	minGiB, err := parseSizeToGiB(storage.MinSize)
+	if err != nil {
+		return 0, 0, err
+	}
+	maxGiB, err := parseSizeToGiB(storage.MaxSize)
+	if err != nil {
+		return 0, 0, err
+	}
+
+	return minGiB, maxGiB, nil
+}
+
+func clampDefaultFlexibleStorage(minGiB int, maxGiB int) int {
+	defaultGiB := defaultFlexibleStorageGiB
+	if minGiB > 0 && defaultGiB < minGiB {
+		defaultGiB = minGiB
+	}
+	if maxGiB > 0 && defaultGiB > maxGiB {
+		defaultGiB = maxGiB
+	}
+
+	return defaultGiB
+}
+
+func parseRequestedStorageGiB(requested string) (int, error) {
+	sizeGiB, err := strconv.Atoi(requested)
+	if err != nil || sizeGiB <= 0 {
+		return 0, breverrors.NewValidationError("--storage must be a positive integer number of GiB")
+	}
+
+	return sizeGiB, nil
+}
+
+func validateFlexibleStorageBounds(instanceType string, sizeGiB int, minGiB int, maxGiB int) error {
+	if minGiB > 0 && sizeGiB < minGiB {
+		return breverrors.NewValidationError(fmt.Sprintf("--storage must be at least %d GiB for instance type %q", minGiB, instanceType))
+	}
+	if maxGiB > 0 && sizeGiB > maxGiB {
+		return breverrors.NewValidationError(fmt.Sprintf("--storage must be at most %d GiB for instance type %q", maxGiB, instanceType))
+	}
+
+	return nil
+}
+
 func resolveLifecycleScript(opts launchableCreateOptions) (string, error) {
 	if opts.Mode != "vm" {
 		return "", nil
@@ -408,33 +453,59 @@ func parseSecureLinks(rawLinks []string) ([]secureLinkSpec, error) {
 	}
 
 	links := make([]secureLinkSpec, 0, len(rawLinks))
-	nameSet := map[string]struct{}{}
-	ctaCount := 0
+	state := newSecureLinkValidationState()
 
 	for _, raw := range rawLinks {
 		link, err := parseSecureLink(raw)
 		if err != nil {
 			return nil, err
 		}
-		if _, exists := nameSet[link.Name]; exists {
-			return nil, breverrors.NewValidationError(fmt.Sprintf("duplicate secure link name %q", link.Name))
-		}
-
-		nameSet[link.Name] = struct{}{}
-		if link.CTA {
-			ctaCount++
+		if err := state.add(link); err != nil {
+			return nil, err
 		}
 
 		links = append(links, link)
 	}
 
-	if ctaCount > maxCTAServiceCount {
-		return nil, breverrors.NewValidationError(fmt.Sprintf("at most %d secure links can have cta=true", maxCTAServiceCount))
+	if err := state.validate(); err != nil {
+		return nil, err
 	}
 
 	return links, nil
 }
 
+type secureLinkValidationState struct {
+	nameSet  map[string]struct{}
+	ctaCount int
+}
+
+func newSecureLinkValidationState() secureLinkValidationState {
+	return secureLinkValidationState{
+		nameSet: map[string]struct{}{},
+	}
+}
+
+func (s *secureLinkValidationState) add(link secureLinkSpec) error {
+	if _, exists := s.nameSet[link.Name]; exists {
+		return breverrors.NewValidationError(fmt.Sprintf("duplicate secure link name %q", link.Name))
+	}
+
+	s.nameSet[link.Name] = struct{}{}
+	if link.CTA {
+		s.ctaCount++
+	}
+
+	return nil
+}
+
+func (s secureLinkValidationState) validate() error {
+	if s.ctaCount > maxCTAServiceCount {
+		return breverrors.NewValidationError(fmt.Sprintf("at most %d secure links can have cta=true", maxCTAServiceCount))
+	}
+
+	return nil
+}
+
 func parseSecureLink(raw string) (secureLinkSpec, error) {
 	values, err := parseFlagAssignments(raw)
 	if err != nil {
diff --git a/pkg/cmd/launchable/doc.md b/pkg/cmd/launchable/doc.md
index e785ce50..f2acfa92 100644
--- a/pkg/cmd/launchable/doc.md
+++ b/pkg/cmd/launchable/doc.md
@@ -131,7 +131,7 @@ Allowed values:
 Default:
 
 ```bash
---view-access public
+--view-access organization
 ```
 
 Examples:
@@ -499,7 +499,7 @@ brev launchable create my-vm \
 What this does:
 
 - creates a VM launchable
-- uses default `public` visibility
+- uses default `organization` visibility
 - enables Jupyter by default
 - uses default storage behavior for the instance type
 - sends no preload file URL