Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

fix(cli): doctor --help prints usage, and a failed run names its reason

M3gA-Mind314f418f2d09
diff --git a/crates/openhuman-cli/src/doctor/args.rs b/crates/openhuman-cli/src/doctor/args.rs
index 1ee2c9e3e7..5033702951 100644
--- a/crates/openhuman-cli/src/doctor/args.rs
+++ b/crates/openhuman-cli/src/doctor/args.rs
@@ -2,6 +2,7 @@ use serde_json::{json, Value};
/// Parsed options for the host-owned doctor command.
pub(super) struct DoctorArgs {
+ pub(super) help: bool,
pub(super) json: bool,
pub(super) lint: bool,
pub(super) severity_min: String,
@@ -25,6 +26,7 @@ impl DoctorArgs {
pub(super) fn parse_args(args: &[String]) -> Result<DoctorArgs, String> {
let mut options = DoctorArgs {
+ help: false,
json: false,
lint: false,
severity_min: "error".into(),
@@ -37,6 +39,7 @@ pub(super) fn parse_args(args: &[String]) -> Result<DoctorArgs, String> {
let mut index = 0;
while index < args.len() {
match args[index].as_str() {
+ "--help" | "-h" | "help" => options.help = true,
"--json" => options.json = true,
"--lint" => options.lint = true,
"--live" => options.tier = "live".into(),
@@ -81,3 +84,20 @@ fn argument_value<'a>(args: &'a [String], index: usize, flag: &str) -> Result<&'
.map(String::as_str)
.ok_or_else(|| format!("missing value for {flag}"))
}
+
+/// Usage text for `doctor --help`.
+pub(super) const USAGE: &str = "\
+Usage: openhuman-core doctor [options]
+
+Run the OpenHuman health checks and print a report.
+
+Options:
+ --json Print the report as JSON
+ --live Also run live checks (may use your session or API key)
+ --lint Exit 1 when a finding reaches --severity-min
+ --severity-min <level> info, warn or error (default: error)
+ --only <check-id> Run only this check (repeatable)
+ --skip <check-id> Skip this check (repeatable)
+ --profile <name> Use this desktop profile
+ -h, --help Show this help
+";
diff --git a/crates/openhuman-cli/src/doctor/args_tests.rs b/crates/openhuman-cli/src/doctor/args_tests.rs
index a80c1ba393..fcd0758160 100644
--- a/crates/openhuman-cli/src/doctor/args_tests.rs
+++ b/crates/openhuman-cli/src/doctor/args_tests.rs
@@ -181,3 +181,30 @@ fn legacy_doctor_namespace_commands_stay_with_the_core_dispatcher() {
assert!(!is_doctor_command(&invocation));
}
}
+
+#[test]
+fn help_flags_ask_for_usage_instead_of_failing() {
+ for flag in ["--help", "-h", "help"] {
+ assert!(args(&[flag]).help, "{flag}");
+ assert!(is_doctor_command(&["doctor".to_owned(), flag.to_owned()]));
+ }
+ assert!(!args(&[]).help);
+ assert!(super::args::USAGE.contains("--severity-min"));
+}
+
+#[test]
+fn a_failed_run_names_a_safe_reason_class() {
+ use super::runner::{failure_output, DoctorFailure};
+ for failure in [
+ DoctorFailure::Runtime,
+ DoctorFailure::Host,
+ DoctorFailure::Rpc,
+ DoctorFailure::NoReport,
+ ] {
+ let text = failure_output(false, failure);
+ assert!(text.starts_with("doctor could not produce a report: "));
+ assert!(text.ends_with(failure.reason()));
+ let json: Value = serde_json::from_str(&failure_output(true, failure)).unwrap();
+ assert_eq!(json, json!({ "ok": false, "reason": failure.reason() }));
+ }
+}
diff --git a/crates/openhuman-cli/src/doctor/runner.rs b/crates/openhuman-cli/src/doctor/runner.rs
index df90170765..0df7a89a36 100644
--- a/crates/openhuman-cli/src/doctor/runner.rs
+++ b/crates/openhuman-cli/src/doctor/runner.rs
@@ -9,6 +9,34 @@ pub(super) fn doctor_report_body(invoke_result: &Value) -> Result<&Value, String
.ok_or_else(|| "doctor RPC response did not include a report".into())
}
+/// Why the CLI doctor produced no report. Each class is a fixed, safe summary:
+/// the underlying errors can carry endpoints or credential context, so they are
+/// never printed.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(super) enum DoctorFailure {
+ /// The async runtime could not be created.
+ Runtime,
+ /// The doctor host could not start (profile selection, config, or boot).
+ Host,
+ /// The core rejected or failed the `doctor_report` call.
+ Rpc,
+ /// The core answered without a report.
+ NoReport,
+}
+
+impl DoctorFailure {
+ pub(super) fn reason(self) -> &'static str {
+ match self {
+ Self::Runtime => "the async runtime could not start",
+ Self::Host => {
+ "the doctor host could not start (profile selection, config or core boot)"
+ }
+ Self::Rpc => "the doctor_report call failed",
+ Self::NoReport => "the core answered without a report",
+ }
+ }
+}
+
pub(super) fn exit_code(options: &DoctorArgs, report: Result<&Value, ()>) -> u8 {
let Ok(report) = report else {
return 2;
@@ -52,10 +80,15 @@ pub(crate) fn run(args: &[String]) -> u8 {
}
};
+ if options.help {
+ print!("{}", super::args::USAGE);
+ return 0;
+ }
+
let tokio = match openhuman_rpc::embed::process::tokio_runtime() {
Ok(runtime) => runtime,
Err(_) => {
- print_runtime_failure(options.json);
+ print_runtime_failure(options.json, DoctorFailure::Runtime);
return 2;
}
};
@@ -77,29 +110,39 @@ pub(crate) fn run(args: &[String]) -> u8 {
}
exit_code(&options, Ok(&report))
}
- Err(()) => {
- print_runtime_failure(options.json);
+ Err(failure) => {
+ print_runtime_failure(options.json, failure);
exit_code(&options, Err(()))
}
}
}
-async fn invoke_report(options: &DoctorArgs) -> Result<Value, ()> {
+async fn invoke_report(options: &DoctorArgs) -> Result<Value, DoctorFailure> {
let runtime = openhuman_rpc::host::doctor_runtime(options.profile.as_deref())
.await
- .map_err(|_| ())?;
+ .map_err(|_| DoctorFailure::Host)?;
let invoke_result = runtime
.core_runtime()
.invoke("openhuman.doctor_report", options.rpc_params())
.await
- .map_err(|_| ())?;
- doctor_report_body(&invoke_result).cloned().map_err(|_| ())
+ .map_err(|_| DoctorFailure::Rpc)?;
+ doctor_report_body(&invoke_result)
+ .cloned()
+ .map_err(|_| DoctorFailure::NoReport)
+}
+
+pub(super) fn failure_output(json: bool, failure: DoctorFailure) -> String {
+ if json {
+ serde_json::json!({ "ok": false, "reason": failure.reason() }).to_string()
+ } else {
+ format!("doctor could not produce a report: {}", failure.reason())
+ }
}
-fn print_runtime_failure(json: bool) {
+fn print_runtime_failure(json: bool, failure: DoctorFailure) {
if json {
- println!("{{\"ok\":false}}");
+ println!("{}", failure_output(json, failure));
} else {
- eprintln!("doctor could not produce a report");
+ eprintln!("{}", failure_output(json, failure));
}
}