feat(cella): replace flag-based create with apply -f <manifest.yaml>

The Sandbox Manifest (sandbox spec 81) is now the only path for
spinning up a Cella from the CLI. The old flag-soup
`latere cella create --name --image --tier --disk --cpu --memory
--auto-stop-minutes --auto-delete-hours --ttl --env --credential
--policy` is gone in favour of a single command:

    latere cella apply -f sandbox.yaml

The CLI does no schema work. It reads the file (or stdin), POSTs
the raw bytes to /v1/sandboxes with
Content-Type: application/yaml, and surfaces the server's
response verbatim. The same body the dashboard's YAML tab and a
curl -H 'Content-Type: application/yaml' send.

Help text, root examples, the policy-sidecar error message, and
the CLI's own docs/cella.md README now teach apply as the
canonical path. Tests rewritten: the legacy --image default test
deleted, four new tests pin the apply-only flag surface, a
round-trip wire test, a stdin path, and the 64 KiB body cap.

Towards sandbox spec 82 / 83 promises (the CLI side users see
the docs and landing page point at).

Author: changkun

README.md

@@ -57,7 +57,7 @@ latere auth login --token <token>
 | **Lux** | Call language models on your identity, no key to allocate: discovery, SDK enablement, chat, usage. | [docs/lux.md](docs/lux.md) |
 
 ```sh
-latere cella create --name demo --tier ephemeral
+latere cella apply -f sandbox.yaml
 latere lux chat --model openai/gpt-4o-mini "Say hi"
 ```
 

docs/cella.md

@@ -4,14 +4,30 @@
 
 ## Quickstart
 
-Create an ephemeral cella and run a command:
-
-```sh
-latere cella create --name demo --tier ephemeral
+Describe a Cella in a YAML file and apply it:
+
+```sh
+cat > sandbox.yaml <<'YAML'
+apiVersion: cella.latere.ai/v1            # Schema version.
+kind: Sandbox
+metadata:
+  name: demo                              # Optional.
+spec:
+  image: ghcr.io/latere-ai/sandbox-base:latest
+  tier: ephemeral                         # Or "persistent" to keep it.
+  lifecycle:
+    autoStop: 15m
+YAML
+
+latere cella apply -f sandbox.yaml
 latere cella exec demo -- sh -lc 'echo hello && pwd'
 latere cella shell demo
 ```
 
+The same YAML works in the dashboard's YAML tab and over the
+public API with `Content-Type: application/yaml`. Full field
+reference: <https://cella.latere.ai/docs/cella/manifest>.
+
 Run a one-shot disposable command. The backend creates an ephemeral
 cella, runs the command, returns output and timing, then deletes the
 cella:
@@ -20,14 +36,6 @@ cella:
 latere cella run --ephemeral --rm -- sh -lc 'echo hello && pwd'
 ```
 
-Create a persistent workspace:
-
-```sh
-latere cella create --name work --tier persistent --disk 10
-latere cella stop work
-latere cella start work
-```
-
 Run a background job and follow logs:
 
 ```sh
@@ -38,7 +46,7 @@ latere cella logs demo "$CMD" --follow
 ## Lifecycle
 
 ```sh
-latere cella create
+latere cella apply -f sandbox.yaml
 latere cella list
 latere cella get <name|id>
 latere cella rename <name|id> <new-name>
@@ -47,22 +55,6 @@ latere cella stop <name|id>
 latere cella delete <name|id>
 ```
 
-Create flags:
-
-```sh
-latere cella create \
-  --name work \
-  --image ghcr.io/latere-ai/sandbox-base:main \
-  --tier persistent \
-  --disk 10 \
-  --auto-stop-minutes 30 \
-  --auto-delete-hours 24 \
-  --ttl 12h \
-  --env GOFLAGS=-count=1 \
-  --credential source-control \
-  --policy default
-```
-
 Tier changes:
 
 ```sh

internal/api/client.go

@@ -201,7 +201,7 @@ func (e *APIError) Error() string {
 	if e.Code == "policy_sidecar_required" {
 		return "cannot create cella: the selected policy requires Cella's credential sidecar, but the server has no complete sidecar configuration for this CLI token.\n" +
 			"This is not a local command syntax problem. Re-run `latere auth login` with the latest CLI, then retry.\n" +
-			"To choose another policy, run `latere cella policy list` and retry with `latere cella create --policy <name>` using a selectable policy where sidecar is `no`.\n" +
+			"To choose another policy, run `latere cella policy list` and set `spec.policy` in your Manifest to a selectable policy where sidecar is `no`.\n" +
 			"If no such policy is available, ask your Latere admin/support to configure the CLI sidecar client or assign a non-sidecar policy.\n" +
 			"server code: policy_sidecar_required"
 	}

internal/api/client_test.go

@@ -18,7 +18,7 @@ func TestAPIErrorPolicySidecarRequiredIsActionable(t *testing.T) {
 		"not a local command syntax problem",
 		"latere auth login",
 		"latere cella policy list",
-		"latere cella create --policy <name>",
+		"spec.policy",
 		"sidecar is `no`",
 		"server code: policy_sidecar_required",
 	} {

internal/commands/cella.go

@@ -115,13 +115,13 @@ Each cella is a PVC-backed workspace plus a Pod for compute. Tier
 window; tier 'persistent' stays until you delete it.`,
 		Example: `  latere cella list
   latere cella policy list
-  latere cella create --name dev --tier persistent --disk 10
+  latere cella apply -f sandbox.yaml
   latere cella shell dev
   latere cella run dev -- python train.py
   latere cella export dev src -o workspace.tar`,
 	}
 	cmd.AddCommand(
-		newCeCreateCmd(),
+		newCeApplyCmd(),
 		newCeListCmd(),
 		newCeGetCmd(),
 		newCeRenameCmd(),
@@ -172,110 +172,95 @@ the remote command's exit code when the command finishes.`,
 	return cmd
 }
 
-// ---- create / list / get / rename / start / stop / delete ----
+// ---- apply / list / get / rename / start / stop / delete ----
 
-func newCeCreateCmd() *cobra.Command {
+// newCeApplyCmd registers `latere cella apply -f <file>`. Reads the
+// SandboxManifest from disk and POSTs the raw bytes to
+// /v1/sandboxes with Content-Type: application/yaml. The server is
+// the authoritative validator, so the CLI does no schema work.
+// "-" reads the manifest from stdin.
+func newCeApplyCmd() *cobra.Command {
 	var (
-		image           string
-		name            string
-		tier            string
-		diskGB          int
-		cpu             string
-		memory          string
-		autoStop        int
-		autoDeleteHours int
-		ttl             string
-		envFlag         []string
-		credentialFlag  []string
-		policy          string
-		apiURL          string
+		file   string
+		apiURL string
 	)
 	cmd := &cobra.Command{
-		Use:   "create",
-		Short: "Create a cella.",
-		Long: `Create a Cella workspace.
-
-By default this creates an ephemeral cella using the standard base
-image and account defaults for disk, CPU, memory, idle timeout, and
-policy. Use --tier persistent for a workspace that survives until
-explicitly deleted.`,
-		Example: `  latere cella create
-  latere cella policy list
-  latere cella create --name dev --tier persistent --disk 10
-  latere cella create --name gpu-test --cpu 2 --memory 8Gi
-  latere cella create --name app --env NODE_ENV=development --credential github
-  latere cella create --policy default-sidecar`,
+		Use:   "apply",
+		Short: "Create a cella from a Sandbox Manifest file.",
+		Long: `Create a Cella from a declarative Sandbox Manifest.
+
+The same YAML accepted by the dashboard's YAML tab and the
+public API. Defaults hit the warm pool, so a Manifest like the
+one below starts in around 300 ms:
+
+  apiVersion: cella.latere.ai/v1        # Schema version.
+  kind: Sandbox
+  metadata:
+    name: dev                           # Optional. Server picks one if omitted.
+  spec:
+    image: ghcr.io/latere-ai/sandbox-base:latest
+    tier: ephemeral                     # Or "persistent" to keep the workspace.
+    lifecycle:
+      autoStop: 15m                     # Stop the compute after this much idle.
+
+Full field reference: https://cella.latere.ai/docs/cella/manifest`,
+		Example: `  latere cella apply -f sandbox.yaml
+  cat sandbox.yaml | latere cella apply -f -`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			c, err := authedClient(apiURL)
+			if strings.TrimSpace(file) == "" {
+				return fmt.Errorf("-f is required (path to a Sandbox Manifest, or - for stdin)")
+			}
+			body, err := readManifestBody(file)
 			if err != nil {
 				return err
 			}
-			env, err := parseKV(envFlag)
+			c, err := authedClient(apiURL)
 			if err != nil {
 				return err
 			}
-			if cmd.Flags().Changed("auto-stop-minutes") && autoStop < 0 {
-				return fmt.Errorf("--auto-stop-minutes must be 0 or greater")
-			}
-			body := map[string]any{
-				"image": image,
-				"name":  name,
-			}
-			if tier != "" {
-				body["tier"] = tier
-			}
-			if diskGB > 0 {
-				body["disk_gb"] = diskGB
-			}
-			if cpu != "" {
-				body["cpu"] = cpu
-			}
-			if memory != "" {
-				body["memory"] = memory
-			}
-			if cmd.Flags().Changed("auto-stop-minutes") {
-				body["auto_stop_minutes"] = autoStop
-			}
-			if autoDeleteHours > 0 {
-				body["auto_delete_hours"] = autoDeleteHours
-			}
-			if ttl != "" {
-				body["ttl"] = ttl
-			}
-			if len(env) > 0 {
-				body["env"] = env
-			}
-			if len(credentialFlag) > 0 {
-				body["credential_catalog"] = credentialFlag
-			}
-			if policy != "" {
-				body["policy"] = policy
-			}
 			var sb sandboxDTO
-			if err := c.PostJSON(cmd.Context(), "/v1/sandboxes", body, &sb); err != nil {
+			if err := c.Do(cmd.Context(), http.MethodPost, "/v1/sandboxes",
+				bytes.NewReader(body), "application/yaml", &sb); err != nil {
 				return err
 			}
 			printSandbox(sb)
 			return nil
 		},
 	}
-	f := cmd.Flags()
-	f.StringVar(&image, "image", "ghcr.io/latere-ai/sandbox-base:latest", "container image")
-	f.StringVar(&name, "name", "", "human slug; server generates one if omitted")
-	f.StringVar(&tier, "tier", "", "ephemeral|persistent (default ephemeral)")
-	f.IntVar(&diskGB, "disk", 0, "PVC size in GB (default 1)")
-	f.StringVar(&cpu, "cpu", "", "CPU limit as a Kubernetes quantity, e.g. 1.5 or 1500m (default plan/account default)")
-	f.StringVar(&memory, "memory", "", "memory limit as a Kubernetes quantity, e.g. 4Gi or 2048Mi (default plan/account default)")
-	f.IntVar(&autoStop, "auto-stop-minutes", 0, "idle timeout in minutes; omit for account default, 0 disables")
-	f.IntVar(&autoDeleteHours, "auto-delete-hours", 0, "ephemeral wall-clock lifetime")
-	f.StringVar(&ttl, "ttl", "", "Go duration TTL alternative to --auto-delete-hours")
-	f.StringArrayVar(&envFlag, "env", nil, "non-secret KEY=VALUE; repeatable")
-	f.StringArrayVar(&credentialFlag, "credential", nil, "trust-plane catalog key to attach; repeatable")
-	f.StringVar(&policy, "policy", "", "named network policy")
-	f.StringVar(&apiURL, "api-url", "", "override Cella API base URL")
+	cmd.Flags().StringVarP(&file, "file", "f", "", "path to a Sandbox Manifest YAML file, or - for stdin")
+	_ = cmd.MarkFlagRequired("file")
+	cmd.Flags().StringVar(&apiURL, "api-url", "", "override Cella API base URL")
 	return cmd
 }
 
+// readManifestBody reads the manifest from path or, if path is "-",
+// from stdin. Capped at 64 KiB to match the server's body limit.
+func readManifestBody(path string) ([]byte, error) {
+	const maxBytes = 64 << 10
+	var r io.Reader
+	if path == "-" {
+		r = os.Stdin
+	} else {
+		f, err := os.Open(path)
+		if err != nil {
+			return nil, fmt.Errorf("open manifest %q: %w", path, err)
+		}
+		defer func() { _ = f.Close() }()
+		r = f
+	}
+	body, err := io.ReadAll(io.LimitReader(r, maxBytes+1))
+	if err != nil {
+		return nil, fmt.Errorf("read manifest: %w", err)
+	}
+	if len(body) > maxBytes {
+		return nil, fmt.Errorf("manifest exceeds %d byte limit", maxBytes)
+	}
+	if len(bytes.TrimSpace(body)) == 0 {
+		return nil, fmt.Errorf("manifest is empty")
+	}
+	return body, nil
+}
+
 func newCeListCmd() *cobra.Command {
 	var (
 		apiURL string
@@ -328,19 +313,19 @@ func newCePolicyCmd() *cobra.Command {
 
 Policies control runtime capabilities such as network shape, workspace
 layout, and whether Cella's credential sidecar is required. The default
-policy is used when 'latere cella create' is run without --policy.
+policy is used when a Manifest's spec.policy is left empty.
 
-Use a selectable policy with:
+Use a selectable policy by setting it in your Manifest:
 
-  latere cella create --policy <name>
+  spec:
+    policy: restricted-network
 
 If create fails because the selected policy requires the sidecar, list
 policies and choose a selectable policy where sidecar is "no", or ask
 an admin to configure the sidecar client for your token.`,
 		Example: `  latere cella policy
   latere cella policy list
-  latere cella policies --json
-  latere cella create --policy restricted-network`,
+  latere cella policies --json`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runPolicyList(cmd.Context(), apiURL, jsonF)
 		},
@@ -354,8 +339,7 @@ an admin to configure the sidecar client for your token.`,
 		Short: "List policy profiles available for new cellas.",
 		Long:  cmd.Long,
 		Example: `  latere cella policy list
-  latere cella policy list --json
-  latere cella create --policy restricted-network`,
+  latere cella policy list --json`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runPolicyList(cmd.Context(), apiURL, jsonF)
 		},
@@ -380,7 +364,7 @@ func runPolicyList(ctx context.Context, apiURL string, jsonF bool) error {
 	}
 	if len(policies) == 0 {
 		fmt.Fprintln(os.Stdout, "No policy profiles are visible to this token.")
-		fmt.Fprintln(os.Stdout, "Ask your Latere admin to assign a selectable policy, then retry `latere cella create --policy <name>`.")
+		fmt.Fprintln(os.Stdout, "Ask your Latere admin to assign a selectable policy, then re-run `latere cella apply` with `spec.policy` set in your Manifest.")
 		return nil
 	}
 	printPolicies(policies)