feat(cli): add help command

docs/reference/cli.md

@@ -6,6 +6,7 @@ The default is `~/.push/config.toml`.
 
 | Command | Purpose |
 | --- | --- |
+| `push help`, `push --help` | Print command and option help without loading config or changing files |
 | `push init [path]` | Create and Git-initialize the one assistant repository; defaults to `./assistant` |
 | `push` | Start the configured channel gateway and scheduler |
 | `push doctor` | Validate config, paths, channel requirements, and required backend binaries |
@@ -20,6 +21,7 @@ Examples:
 
 ```sh
 push init ~/Code/assistant
+push help
 push doctor
 push
 push restart
@@ -29,7 +31,7 @@ push job runs repo-review
 ```
 
 Unknown commands and missing values fail with the accepted command forms. The
-CLI does not currently provide shell completion or a generated `--help` page.
+CLI does not currently provide shell completion.
 
 `push restart` targets the service definitions documented by Push:
 `com.owainlewis.push` under launchd on macOS and the `push.service` user unit

src/main.rs

@@ -30,13 +30,36 @@ mod voice;
 use anyhow::{bail, Context, Result};
 
 const DEFAULT_CONFIG_PATH: &str = "~/.push/config.toml";
+const HELP: &str = "Push turns coding agents into a personal assistant you can text.
+
+Usage: push [OPTIONS] [COMMAND]
+
+Commands:
+  help              Print this help
+  init [path]       Create an assistant repository (default: ./assistant)
+  doctor            Validate the configuration and dependencies
+  restart           Restart the installed gateway service
+  job validate      Validate all installed jobs
+  job list          List installed jobs
+  job show <name>   Show an installed job
+  job run <name>    Run an installed job
+  job runs [name]   Show job run history
+
+Options:
+  --config <path>   Use a configuration file (default: ~/.push/config.toml)
+  -h, --help        Print help
+";
 
 #[tokio::main]
 async fn main() -> Result<()> {
     tracing_subscriber::fmt().with_target(false).init();
 
     let args = Args::parse(std::env::args().skip(1).collect())?;
     match args.command {
+        Command::Help => {
+            print!("{HELP}");
+            Ok(())
+        }
         Command::Init(path) => {
             let result = assistant::init(&path, &args.config_path)?;
             println!("Initialized assistant at {}", result.root.display());
@@ -121,6 +144,7 @@ struct Args {
 
 #[derive(Debug, PartialEq, Eq)]
 enum Command {
+    Help,
     Run,
     Init(String),
     Doctor,
@@ -139,6 +163,16 @@ enum JobCommand {
 
 impl Args {
     fn parse(args: Vec<String>) -> Result<Self> {
+        if args
+            .iter()
+            .any(|arg| matches!(arg.as_str(), "-h" | "--help"))
+        {
+            return Ok(Self {
+                command: Command::Help,
+                config_path: DEFAULT_CONFIG_PATH.to_string(),
+            });
+        }
+
         let mut config_path = DEFAULT_CONFIG_PATH.to_string();
         let mut positional = Vec::new();
         let mut i = 0;
@@ -159,6 +193,7 @@ impl Args {
         }
         let command = match positional.iter().map(String::as_str).collect::<Vec<_>>().as_slice() {
             [] => Command::Run,
+            ["help"] => Command::Help,
             ["init"] => Command::Init("./assistant".to_string()),
             ["init", path] => Command::Init((*path).to_string()),
             ["doctor"] => Command::Doctor,
@@ -170,7 +205,7 @@ impl Args {
             ["job", "runs"] => Command::Job(JobCommand::Runs(None)),
             ["job", "runs", name] => Command::Job(JobCommand::Runs(Some((*name).to_string()))),
             _ => bail!(
-                "unknown command; expected init [path], doctor, restart, job validate, job list, job show <name>, job run <name>, job runs [<name>], or --config <path>"
+                "unknown command; expected help, init [path], doctor, restart, job validate, job list, job show <name>, job run <name>, job runs [<name>], or --config <path>"
             ),
         };
         Ok(Self {
@@ -328,6 +363,30 @@ mod tests {
         );
     }
 
+    #[test]
+    fn parses_help_without_treating_it_as_a_command_argument() {
+        assert_eq!(
+            Args::parse(vec!["help".into()]).unwrap(),
+            Args {
+                command: Command::Help,
+                config_path: DEFAULT_CONFIG_PATH.to_string(),
+            }
+        );
+        assert_eq!(
+            Args::parse(vec!["--help".into()]).unwrap(),
+            Args {
+                command: Command::Help,
+                config_path: DEFAULT_CONFIG_PATH.to_string(),
+            }
+        );
+        assert_eq!(
+            Args::parse(vec!["job".into(), "--help".into()])
+                .unwrap()
+                .command,
+            Command::Help
+        );
+    }
+
     #[test]
     fn parses_all_job_commands_with_config_anywhere() {
         assert_eq!(

tests/init_cli.rs

@@ -2,6 +2,37 @@ use std::process::Command;
 
 use uuid::Uuid;
 
+#[test]
+fn help_commands_print_usage_without_creating_files() {
+    let root = temp_dir("help");
+    let home = root.join("home");
+    let workdir = root.join("workdir");
+    std::fs::create_dir_all(&home).unwrap();
+    std::fs::create_dir_all(&workdir).unwrap();
+
+    for args in [&["help"][..], &["init", "--help"][..]] {
+        let output = Command::new(env!("CARGO_BIN_EXE_push"))
+            .args(args)
+            .current_dir(&workdir)
+            .env("HOME", &home)
+            .output()
+            .unwrap();
+
+        assert!(
+            output.status.success(),
+            "{}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        assert!(stdout.contains("Usage: push"));
+        assert!(stdout.contains("restart"));
+        assert!(output.stderr.is_empty());
+    }
+    assert_eq!(std::fs::read_dir(&workdir).unwrap().count(), 0);
+    assert_eq!(std::fs::read_dir(&home).unwrap().count(), 0);
+    let _ = std::fs::remove_dir_all(root);
+}
+
 #[test]
 fn init_without_path_creates_assistant_in_current_directory() {
     let root = temp_dir("default");