Merge pull request #48 from auths-dev/feature/top-level-pair-command

feat: add `auths pair` as a top-level command

Author: bordumb

.pre-commit-config.yaml

@@ -35,6 +35,13 @@ repos:
         types: [rust]
         pass_filenames: false
 
+      - id: gen-docs-check
+        name: cargo xtask gen-docs --check
+        entry: cargo xtask gen-docs --check
+        language: system
+        files: (crates/auths-cli/src/|crates/xtask/src/gen_docs|docs/cli/commands/)
+        pass_filenames: false
+
       - id: cargo-deny
         name: cargo deny (licenses + bans)
         entry: bash -c 'cargo deny check > .cargo/cargo-deny.log 2>&1; exit $?'

crates/auths-cli/README.md

@@ -13,6 +13,13 @@ auths verify HEAD
 
 That's it. `auths init` generates keys, creates your identity, and configures Git signing.
 
+### Link another device
+
+```bash
+auths pair                         # On existing device — shows QR/code
+auths pair --join ABC123           # On new device — enter the code
+```
+
 ## The Basics
 
 ### `auths sign` — Sign a commit or artifact

crates/auths-cli/src/cli.rs

@@ -12,6 +12,7 @@ use crate::commands::completions::CompletionsCommand;
 use crate::commands::config::ConfigCommand;
 use crate::commands::debug::DebugCmd;
 use crate::commands::device::DeviceCommand;
+use crate::commands::device::pair::PairCommand;
 use crate::commands::doctor::DoctorCommand;
 use crate::commands::emergency::EmergencyCommand;
 use crate::commands::git::GitCommand;
@@ -91,6 +92,7 @@ pub enum RootCommand {
     Whoami(WhoamiCommand),
     Tutorial(LearnCommand),
     Doctor(DoctorCommand),
+    Pair(PairCommand),
     #[command(hide = true)]
     Completions(CompletionsCommand),
     #[command(hide = true)]

crates/auths-cli/src/commands/device/mod.rs

@@ -10,6 +10,12 @@ use crate::commands::executable::ExecutableCommand;
 use crate::config::CliConfig;
 use anyhow::Result;
 
+impl ExecutableCommand for PairCommand {
+    fn execute(&self, ctx: &CliConfig) -> Result<()> {
+        handle_pair(self.clone(), &ctx.env_config)
+    }
+}
+
 impl ExecutableCommand for DeviceCommand {
     fn execute(&self, ctx: &CliConfig) -> Result<()> {
         handle_device(

crates/auths-cli/src/commands/learn.rs

@@ -476,11 +476,11 @@ fn section_linking_device() -> Result<()> {
     println!("  To link a new device:");
     println!();
     println!("    {} On your existing device:", "1.".cyan());
-    println!("       {}", "$ auths pair start".cyan());
+    println!("       {}", "$ auths pair".cyan());
     println!("       {}", "Scan this QR code or enter: ABC123".dimmed());
     println!();
     println!("    {} On your new device:", "2.".cyan());
-    println!("       {}", "$ auths pair join --code ABC123".cyan());
+    println!("       {}", "$ auths pair --join ABC123".cyan());
     println!();
     println!(
         "  This creates an {} that authorizes the new device",

crates/auths-cli/src/main.rs

@@ -68,6 +68,7 @@ fn run() -> Result<()> {
         RootCommand::Whoami(cmd) => cmd.execute(&ctx),
         RootCommand::Tutorial(cmd) => cmd.execute(&ctx),
         RootCommand::Doctor(cmd) => cmd.execute(&ctx),
+        RootCommand::Pair(cmd) => cmd.execute(&ctx),
         RootCommand::Completions(cmd) => cmd.execute(&ctx),
         RootCommand::Emergency(cmd) => cmd.execute(&ctx),
         RootCommand::Id(cmd) => cmd.execute(&ctx),

crates/xtask/src/gen_docs.rs

@@ -29,6 +29,11 @@ const COMMANDS: &[Cmd] = &[
         marker: "auths status",
         doc_file: "docs/cli/commands/primary.md",
     },
+    Cmd {
+        args: &["pair"],
+        marker: "auths pair",
+        doc_file: "docs/cli/commands/primary.md",
+    },
     // --- device ---
     Cmd {
         args: &["device", "link"],

docs/cli/commands/primary.md

@@ -62,3 +62,26 @@ auths status
 | `-q, --quiet` | — | Suppress non-essential output |
 | `--repo <REPO>` | — | Override the local storage directory (default: ~/.auths) |
 <!-- END GENERATED: auths status -->
+
+---
+
+## auths pair
+
+```bash
+auths pair
+```
+
+<!-- BEGIN GENERATED: auths pair -->
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--join <CODE>` | — |  |
+| `--registry <URL>` | — |  |
+| `--no-qr` | — |  |
+| `--timeout <SECONDS>` | — |  |
+| `--offline` | — |  |
+| `--capabilities <CAPABILITIES>` | — |  |
+| `--no-mdns` | — |  |
+| `--json` | — |  |
+| `-q, --quiet` | — |  |
+| `--repo <REPO>` | — |  |
+<!-- END GENERATED: auths pair -->