Api 159/better error handling in the client (#380)

example,

<img width="1108" height="73" alt="Screenshot 2026-03-25 at 12 19 57 AM"
src="https://github.com/user-attachments/assets/905010c2-9e6f-4517-a1ee-cb59131ac141"
/>


this adds a unified cli_error.rs handler to convert OxenError into user
readable error. so far we've been abusing oxenError::basic_str() and
bespoke eprintln!() at various layers. this should allow us to bubble up
the actual error message and handle it at a higher level.

---------

Co-authored-by: Nathan Stocks <nathan.s@oxen.ai>

Author: subygan

.claude/CLAUDE.md

@@ -105,6 +105,7 @@ oxen push origin main               # Push to remote
 - When changing something that is documented in nearby code, or appears in any markdown files in the repository, update the affected documentation.
 - When prompted to always do something a certain way in general, add an entry to this section of the CLAUDE.md file.
 - When calling `get_staged_db_manager`, follow the doc comment on that function: drop the returned `StagedDBManager` as soon as possible (via a block scope or explicit `drop()`) to avoid holding the shared database handle longer than necessary.
+- When altering the `OxenError` enum, consider whether a hint needs to be added or updated in the `hint` method.
 - After changing any Rust code, verify that tests pass with the `bin/test-rust` script (not `cargo`). The script is documented in a comment at the top of its file.
 
 # Testing Rules

Cargo.lock

@@ -0,0 +1,11 @@
+use colored::Colorize;
+use liboxen::error::OxenError;
+
+/// Print an OxenError to stderr with colored prefix and optional hints.
+pub fn print_error(err: &OxenError) {
+    eprintln!("{} {}", "Error:".red().bold(), err);
+
+    if let Some(hint) = err.hint() {
+        eprintln!("  {} {}", "hint:".cyan().bold(), hint);
+    }
+}

crates/cli/src/cli_error.rs

@@ -44,10 +44,7 @@ impl RunCmd for AddCmd {
             .get_many::<String>("files")
             .expect("Must supply files")
             .map(|p| -> Result<PathBuf, OxenError> {
-                let current_dir = std::env::current_dir().map_err(|e| {
-                    log::warn!("Failed to get current directory: {e}");
-                    OxenError::basic_str(format!("Failed to get current directory: {e}"))
-                })?;
+                let current_dir = std::env::current_dir()?;
                 let joined_path = current_dir.join(p);
 
                 util::fs::canonicalize(&joined_path).or_else(|_| Ok(joined_path))

crates/cli/src/cmd/add.rs

@@ -83,7 +83,7 @@ impl RunCmd for BranchCmd {
         if let Some(subcommand) = args.subcommand() {
             match subcommand {
                 (unlock::NAME, args) => unlock::BranchUnlockCmd.run(args).await,
-                (cmd, _) => Err(OxenError::basic_str(format!("Unknown subcommand {cmd}"))),
+                (cmd, _) => Err(OxenError::unknown_subcommand("branch", cmd)),
             }
         } else if args.get_flag("all") {
             self.list_all_branches(&repo).await
@@ -202,9 +202,7 @@ impl BranchCmd {
         let remote = repo
             .get_remote(remote_name)
             .ok_or(OxenError::remote_not_set(remote_name))?;
-        let remote_repo = api::client::repositories::get_by_remote(&remote)
-            .await?
-            .ok_or(OxenError::remote_not_found(remote.clone()))?;
+        let remote_repo = api::client::repositories::get_by_remote(&remote).await?;
 
         let branches = api::client::branches::list(&remote_repo).await?;
         for branch in branches.iter() {

crates/cli/src/cmd/branch.rs

@@ -48,9 +48,7 @@ impl RunCmd for BranchUnlockCmd {
         let remote = repository
             .get_remote(remote_name)
             .ok_or(OxenError::remote_not_set(remote_name))?;
-        let remote_repo = api::client::repositories::get_by_remote(&remote)
-            .await?
-            .ok_or(OxenError::remote_not_found(remote.clone()))?;
+        let remote_repo = api::client::repositories::get_by_remote(&remote).await?;
 
         // Unlock the branch
         api::client::branches::unlock(&remote_repo, branch).await?;

crates/cli/src/cmd/branch/unlock.rs

@@ -100,11 +100,12 @@ impl RunCmd for CloneCmd {
             .collect();
         let depth: Option<i32> = args
             .get_one::<String>("depth")
-            .map(|s| s.parse().expect("Invalid depth, must be an integer"));
+            .map(|s| s.parse::<i32>().map_err(OxenError::ParseIntError))
+            .transpose()?;
         let is_vfs = args.get_flag("vfs");
         let is_remote = args.get_flag("remote");
 
-        let current_dir = std::env::current_dir().expect("Could not get current working directory");
+        let current_dir = std::env::current_dir()?;
         let dst: PathBuf = match args.get_one::<String>("DESTINATION") {
             Some(dir_name) => {
                 let path = Path::new(dir_name);

crates/cli/src/cmd/clone.rs

@@ -116,10 +116,8 @@ fn get_message_from_editor(maybe_config: Option<&UserConfig>) -> Result<String,
                      # Lines starting with '#' will be ignored, and an empty message aborts the commit.\n";
 
     {
-        let mut file = std::fs::File::create(&temp_path)
-            .map_err(|e| OxenError::basic_str(format!("Failed to create temp file: {e}")))?;
-        file.write_all(template.as_bytes())
-            .map_err(|e| OxenError::basic_str(format!("Failed to write to temp file: {e}")))?;
+        let mut file = std::fs::File::create(&temp_path)?;
+        file.write_all(template.as_bytes())?;
     }
 
     // Spawn the editor
@@ -133,8 +131,7 @@ fn get_message_from_editor(maybe_config: Option<&UserConfig>) -> Result<String,
     let status = std::process::Command::new(parts[0])
         .args(&parts[1..])
         .arg(&temp_path)
-        .status()
-        .map_err(|e| OxenError::basic_str(format!("Failed to open editor '{editor}': {e}")))?;
+        .status()?;
 
     if !status.success() {
         return Err(OxenError::basic_str(format!(
@@ -143,8 +140,7 @@ fn get_message_from_editor(maybe_config: Option<&UserConfig>) -> Result<String,
     }
 
     // Read the file and strip comments
-    let contents = std::fs::read_to_string(&temp_path)
-        .map_err(|e| OxenError::basic_str(format!("Failed to read temp file: {e}")))?;
+    let contents = std::fs::read_to_string(&temp_path)?;
     let _ = std::fs::remove_file(&temp_path);
 
     let message: String = contents

crates/cli/src/cmd/commit.rs

@@ -101,77 +101,38 @@ impl RunCmd for ConfigCmd {
     async fn run(&self, args: &clap::ArgMatches) -> Result<(), OxenError> {
         // Non-Repo Dependent
         if let Some(name) = args.get_one::<String>("name") {
-            match self.set_user_name(name) {
-                Ok(_) => {}
-                Err(err) => {
-                    eprintln!("{err}")
-                }
-            }
+            self.set_user_name(name)?;
         }
 
         if let Some(email) = args.get_one::<String>("email") {
-            match self.set_user_email(email) {
-                Ok(_) => {}
-                Err(err) => {
-                    eprintln!("{err}")
-                }
-            }
+            self.set_user_email(email)?;
         }
 
         if let Some(auth) = args.get_many::<String>("auth-token") {
-            if let [host, token] = auth.collect::<Vec<_>>()[..] {
-                match self.set_auth_token(host, token) {
-                    Ok(_) => {}
-                    Err(err) => {
-                        eprintln!("{err}")
-                    }
-                }
-            } else {
-                eprintln!("invalid arguments for --auth");
-            }
+            let values: Vec<_> = auth.collect();
+            // clap enforces number_of_values(2), so this is guaranteed
+            self.set_auth_token(values[0], values[1])?;
         }
 
         if let Some(default_host) = args.get_one::<String>("default-host") {
-            match self.set_default_host(default_host) {
-                Ok(_) => {}
-                Err(err) => {
-                    eprintln!("{err}")
-                }
-            }
+            self.set_default_host(default_host)?;
         }
 
         if let Some(editor) = args.get_one::<String>("editor") {
-            match self.set_editor(editor) {
-                Ok(_) => {}
-                Err(err) => {
-                    eprintln!("{err}")
-                }
-            }
+            self.set_editor(editor)?;
         }
 
         // Repo Dependent
         if let Some(remote) = args.get_many::<String>("set-remote") {
             let mut repo = LocalRepository::from_current_dir()?;
-            if let [name, url] = remote.collect::<Vec<_>>()[..] {
-                match self.set_remote(&mut repo, name, url) {
-                    Ok(_) => {}
-                    Err(err) => {
-                        eprintln!("{err}")
-                    }
-                }
-            } else {
-                eprintln!("invalid arguments for --set-remote");
-            }
+            let values: Vec<_> = remote.collect();
+            // clap enforces number_of_values(2), so this is guaranteed
+            self.set_remote(&mut repo, values[0], values[1])?;
         }
 
         if let Some(name) = args.get_one::<String>("delete-remote") {
             let mut repo = LocalRepository::from_current_dir()?;
-            match self.delete_remote(&mut repo, name) {
-                Ok(_) => {}
-                Err(err) => {
-                    eprintln!("{err}")
-                }
-            }
+            self.delete_remote(&mut repo, name)?;
         }
 
         if let Some(path) = args
@@ -192,9 +153,7 @@ impl RunCmd for ConfigCmd {
             let storage_opts = StorageOpts::from_args(Some(backend), Some(path), bucket)?;
 
             let mut repo = LocalRepository::from_current_dir()?;
-            self.set_version_store(&mut repo, storage_opts)
-                .await
-                .map_err(|e| OxenError::basic_str(format!("{e}")))?;
+            self.set_version_store(&mut repo, storage_opts).await?;
         }
 
         Ok(())

crates/cli/src/cmd/config.rs

@@ -43,18 +43,17 @@ impl RunCmd for DbCmd {
         let sub_commands = self.get_subcommands();
         if let Some((name, sub_matches)) = args.subcommand() {
             let Some(cmd) = sub_commands.get(name) else {
-                eprintln!("Unknown schema subcommand {name}");
-                return Err(OxenError::basic_str(format!(
-                    "Unknown schema subcommand {name}"
-                )));
+                return Err(OxenError::unknown_subcommand("db", name));
             };
 
             // Calling await within an await is making it complain?
             tokio::task::block_in_place(|| {
                 tokio::runtime::Handle::current().block_on(cmd.run(sub_matches))
             })?;
         } else {
-            return Err(OxenError::basic_str("No subcommand provided"));
+            return Err(OxenError::basic_str(
+                "No db subcommand provided. Run `oxen db --help` for usage.",
+            ));
         }
 
         Ok(())