Devbox sparse folder UX and cache intents

README.md

@@ -136,6 +136,11 @@ devbox login
 devbox share <folder>
 devbox clone
 devbox clone <name> [target]
+devbox clone <name> [target] --sparse
+devbox warm <path>
+devbox hydrate <path>
+devbox keep <path>
+devbox free-space <path>
 devbox status
 devbox doctor
 devbox pause|resume|unlink [name]
@@ -196,9 +201,12 @@ loom doctor ./sparse-target
 
 `devbox share <folder>` registers the shared folder, configures the hidden Loom sync endpoint, syncs
 the folder, and starts live sync. `devbox clone` lists folders available to this account; `devbox
-clone <name> [target]` materializes a shared folder on this machine and starts live sync. Tokens,
-pack names, cursors, remotes, and `devbox://` URLs are not printed in normal product output. Debug
-and engine-level operations remain under `loom`.
+clone <name> [target]` materializes a shared folder on this machine and starts live sync.
+`devbox clone --sparse` links the folder first and lets `devbox warm`, `devbox hydrate`,
+`devbox keep`, and `devbox free-space` control what stays local. Tokens, pack names, cursors,
+remotes, and `devbox://` URLs are not printed in normal product output. Debug and engine-level
+operations remain under `loom`. See [docs/devbox/sparse-folders.md](docs/devbox/sparse-folders.md)
+for the hydrate versus keep distinction and current CLI-only limitations.
 
 The current CLI can create/list/show/restore local snapshots and scan pending local changes:
 

devbox/crates/devbox-cli/src/main.rs

@@ -70,6 +70,10 @@ fn main() -> ExitCode {
         Some("pause") => product::run_command("pause", &args[1..]),
         Some("resume") => product::run_command("resume", &args[1..]),
         Some("unlink") => product::run_command("unlink", &args[1..]),
+        Some("warm") => product::run_command("warm", &args[1..]),
+        Some("hydrate") => product::run_command("hydrate", &args[1..]),
+        Some("keep") => product::run_command("keep", &args[1..]),
+        Some("free-space") => product::run_command("free-space", &args[1..]),
         Some("scan") => run_scan(&args[1..]),
         Some("init") => run_init(&args[1..]),
         Some("auth") => run_auth(&args[1..]),
@@ -6672,19 +6676,14 @@ fn open_existing_metadata_store(db_path: &str) -> Result<Store, Box<dyn std::err
 
 fn run_status(args: &[String]) -> ExitCode {
     match args {
-        [] => product::run_status(),
         [flag, path] if flag == "--db" => match status_for_db(path) {
             Ok(()) => ExitCode::SUCCESS,
             Err(error) => {
                 eprintln!("devbox: {error}");
                 ExitCode::from(1)
             }
         },
-        _ => {
-            eprintln!("devbox: status accepts either no arguments or --db <PATH>");
-            eprintln!("Usage: devbox status --db <PATH>");
-            ExitCode::from(2)
-        }
+        _ => product::run_status(args),
     }
 }
 
@@ -6780,6 +6779,10 @@ fn print_help() {
     println!("  clone      Materialize a shared folder on this machine");
     println!("  manage     Manage a shared folder");
     println!("  status     Show shared-folder and machine sync status");
+    println!("  warm       Download useful small files for a folder path");
+    println!("  hydrate    Download a path or folder exactly");
+    println!("  keep       Protect a path from free-space cleanup");
+    println!("  free-space Safely remove backed-up local bytes");
     println!("  doctor     Check this machine and point to folder diagnostics");
     println!("  pause      Pause sync for a shared folder");
     println!("  resume     Resume sync for a shared folder");