feat: auto-install shell completions

Make shell arg optional in `completions` (auto-detects from $SHELL).
Add `--install` flag that appends eval line to ~/.zshrc/~/.bashrc or
writes fish completions file. Idempotent — skips if already configured.
Install script now runs `completions --install` automatically.

Author: liberuum

README.md

@@ -220,7 +220,8 @@ switchboard import ./backup/*.phd --drive another-drive
 | `switchboard interactive` | Launch interactive REPL mode |
 | `switchboard update` | Self-update to the latest release (shows changelog) |
 | `switchboard update --check` | Check for updates without installing |
-| `switchboard completions <shell>` | Generate shell completions (bash/zsh/fish) |
+| `switchboard completions [shell]` | Generate shell completions (auto-detects shell) |
+| `switchboard completions --install` | Auto-install completions into your shell config |
 | `switchboard guide <topic>` | Built-in documentation |
 
 ## Global Flags
@@ -361,17 +362,18 @@ Features:
 
 ## Shell Completions
 
-Generate completions for your shell and add them to your shell config:
+The easiest way to set up tab-completion is:
 
 ```bash
-# Bash
-switchboard completions bash >> ~/.bashrc
+switchboard completions --install
+```
+
+This auto-detects your shell and adds completions to your config file (`~/.zshrc`, `~/.bashrc`, or fish completions dir). The installer also runs this automatically.
 
-# Zsh
-switchboard completions zsh >> ~/.zshrc
+For manual setup, you can output raw completions:
 
-# Fish
-switchboard completions fish >> ~/.config/fish/completions/switchboard.fish
+```bash
+switchboard completions bash   # or zsh, fish
 ```
 
 ## Built-in Documentation

install.sh

@@ -131,6 +131,11 @@ install() {
       ;;
   esac
 
+  # --- setup shell completions -----------------------------------------------
+
+  info "Setting up shell completions"
+  "${INSTALL_DIR}/${BINARY_NAME}" completions --install 2>/dev/null || true
+
   # --- welcome message -------------------------------------------------------
 
   echo ""

src/cli/completions.rs

@@ -1,13 +1,130 @@
-use anyhow::Result;
-use clap::CommandFactory;
+use anyhow::{Context, Result, bail};
+use clap::{Args, CommandFactory};
 use clap_complete::{Shell, generate};
+use colored::Colorize;
 use std::io;
+use std::path::PathBuf;
 
 use crate::cli::Cli;
 
-pub fn run(shell: Shell) -> Result<()> {
-    let mut cmd = Cli::command();
-    let name = cmd.get_name().to_string();
-    generate(shell, &mut cmd, name, &mut io::stdout());
+#[derive(Args)]
+pub struct CompletionsArgs {
+    /// Shell to generate completions for (auto-detected from $SHELL if omitted)
+    pub shell: Option<Shell>,
+
+    /// Install completions into your shell config file
+    #[arg(long)]
+    pub install: bool,
+}
+
+// ── Shell detection ────────────────────────────────────────────────────────
+
+fn detect_shell() -> Result<Shell> {
+    let shell_env = std::env::var("SHELL").unwrap_or_default();
+    if shell_env.contains("zsh") {
+        Ok(Shell::Zsh)
+    } else if shell_env.contains("bash") {
+        Ok(Shell::Bash)
+    } else if shell_env.contains("fish") {
+        Ok(Shell::Fish)
+    } else {
+        bail!(
+            "Could not detect your shell from $SHELL ({shell_env}).\n\
+             Specify it explicitly: switchboard completions bash|zsh|fish"
+        )
+    }
+}
+
+fn rc_file(shell: Shell) -> Result<PathBuf> {
+    let home = dirs::home_dir().context("Could not determine home directory")?;
+    match shell {
+        Shell::Bash => Ok(home.join(".bashrc")),
+        Shell::Zsh => Ok(home.join(".zshrc")),
+        Shell::Fish => Ok(home
+            .join(".config/fish/completions")
+            .join("switchboard.fish")),
+        _ => bail!("Auto-install is not supported for {shell:?}. Add completions manually."),
+    }
+}
+
+fn eval_line(shell: Shell) -> &'static str {
+    match shell {
+        Shell::Bash => r#"eval "$(switchboard completions bash)""#,
+        Shell::Zsh => r#"eval "$(switchboard completions zsh)""#,
+        _ => unreachable!(),
+    }
+}
+
+// ── Entry point ────────────────────────────────────────────────────────────
+
+pub fn run(args: CompletionsArgs) -> Result<()> {
+    let shell = match args.shell {
+        Some(s) => s,
+        None => detect_shell()?,
+    };
+
+    if args.install {
+        install_completions(shell)
+    } else {
+        let mut cmd = Cli::command();
+        let name = cmd.get_name().to_string();
+        generate(shell, &mut cmd, name, &mut io::stdout());
+        Ok(())
+    }
+}
+
+// ── Installer ──────────────────────────────────────────────────────────────
+
+fn install_completions(shell: Shell) -> Result<()> {
+    let target = rc_file(shell)?;
+
+    match shell {
+        Shell::Fish => {
+            // Fish: write completions directly to the completions directory
+            if let Some(parent) = target.parent() {
+                std::fs::create_dir_all(parent)?;
+            }
+            let mut buf = Vec::new();
+            let mut cmd = Cli::command();
+            let name = cmd.get_name().to_string();
+            generate(shell, &mut cmd, name, &mut buf);
+            std::fs::write(&target, &buf)?;
+            println!("{} Wrote completions to {}", "✓".green(), target.display());
+        }
+        Shell::Bash | Shell::Zsh => {
+            let line = eval_line(shell);
+
+            // Check if already installed
+            if target.exists() {
+                let contents = std::fs::read_to_string(&target)?;
+                if contents.contains("switchboard completions") {
+                    println!(
+                        "{} Completions already configured in {}",
+                        "✓".green(),
+                        target.display()
+                    );
+                    return Ok(());
+                }
+            }
+
+            // Append eval line to rc file
+            use std::io::Write;
+            let mut file = std::fs::OpenOptions::new()
+                .create(true)
+                .append(true)
+                .open(&target)?;
+            writeln!(file)?;
+            writeln!(file, "# Switchboard CLI completions")?;
+            writeln!(file, "{line}")?;
+
+            println!("{} Added completions to {}", "✓".green(), target.display());
+            println!(
+                "  Restart your shell or run: {}",
+                format!("source {}", target.display()).dimmed()
+            );
+        }
+        _ => bail!("Auto-install is not supported for {shell:?}. Add completions manually."),
+    }
+
     Ok(())
 }

src/cli/guide.rs

@@ -659,7 +659,8 @@ TOOLS
   interactive (or -i)           Launch REPL mode
   update [--check]              Self-update to latest release
   schema                        Dump GraphQL schema
-  completions <shell>           Generate shell completions
+  completions [shell]           Generate shell completions
+  completions --install          Auto-install completions into shell config
   guide <topic>                 Built-in documentation
 
 GLOBAL FLAGS

src/cli/interactive.rs

@@ -92,6 +92,7 @@ impl ReplHelper {
             "introspect".into(),
             "update".into(),
             "update --check".into(),
+            "completions --install".into(),
             "guide ".into(),
             // REPL-only
             "help".into(),

src/cli/mod.rs

@@ -26,7 +26,6 @@ use colored::Colorize;
 
 use crate::output::OutputFormat;
 use clap::{Parser, Subcommand};
-use clap_complete::Shell;
 
 #[derive(Parser)]
 #[command(name = "switchboard", about = "CLI for Switchboard GraphQL instances")]
@@ -142,11 +141,8 @@ pub enum Commands {
     #[command(subcommand)]
     Guide(guide::GuideCommand),
 
-    /// Generate shell completions
-    Completions {
-        /// Shell to generate completions for
-        shell: Shell,
-    },
+    /// Generate shell completions (auto-detects shell, or specify explicitly)
+    Completions(completions::CompletionsArgs),
 }
 
 /// Central dispatcher shared by both the CLI entry point and the interactive REPL.
@@ -181,7 +177,7 @@ pub async fn dispatch(
         Commands::Update(args) => update::run(args.check, quiet).await,
         Commands::Interactive => anyhow::bail!("Already in interactive mode"),
         Commands::Guide(topic) => guide::run(topic),
-        Commands::Completions { shell } => completions::run(shell),
+        Commands::Completions(args) => completions::run(args),
     }
 }