feat: add shell completions and improve switch UX

README.md

@@ -33,6 +33,10 @@ Install with npm:
 npm install -g @loongphy/codex-auth
 ```
 
+Installed command:
+
+- `codex-auth`
+
   You can also run it without a global install:
 
 ```shell
@@ -83,6 +87,39 @@ Detailed command documentation lives in [docs/commands/README.md](./docs/command
 | Command | Description |
 |---------|-------------|
 | [`codex-auth config live --interval <seconds>`](./docs/commands/config.md) | Configure live TUI refresh interval |
+| `codex-auth completion <bash|zsh|fish>` | Print a shell completion script |
+
+## Shell Completion
+
+Generate completions with:
+
+```shell
+codex-auth completion bash
+codex-auth completion zsh
+codex-auth completion fish
+```
+
+Install Fish completions with:
+
+```shell
+mkdir -p ~/.config/fish/completions
+codex-auth completion fish > ~/.config/fish/completions/codex-auth.fish
+source ~/.config/fish/completions/codex-auth.fish
+```
+
+Install Bash completions with:
+
+```shell
+mkdir -p ~/.local/share/bash-completion/completions
+codex-auth completion bash > ~/.local/share/bash-completion/completions/codex-auth
+```
+
+Install Zsh completions with:
+
+```shell
+mkdir -p ~/.zsh/completions
+codex-auth completion zsh > ~/.zsh/completions/_codex-auth
+```
 
 ## Quick Examples
 

bin/codex-auth.js

@@ -80,6 +80,10 @@ function resolveBinary() {
     }
     return binaryPath;
   } catch (error) {
+    const localBinaryPath = resolveLocalBinary();
+    if (localBinaryPath) {
+      return localBinaryPath;
+    }
     console.error(
       `Missing platform package ${packageName}. Reinstall @loongphy/codex-auth on ${process.platform}/${process.arch}.`
     );
@@ -90,6 +94,15 @@ function resolveBinary() {
   }
 }
 
+function resolveLocalBinary() {
+  const binaryName = process.platform === "win32" ? "codex-auth.exe" : "codex-auth";
+  const localBinaryPath = path.join(__dirname, "..", "zig-out", "bin", binaryName);
+  if (fs.existsSync(localBinaryPath)) {
+    return localBinaryPath;
+  }
+  return null;
+}
+
 const binaryPath = resolveBinary();
 const child = spawnSync(binaryPath, process.argv.slice(2), {
   stdio: "inherit",

docs/commands/README.md

@@ -14,6 +14,7 @@ This directory documents command behavior by command. Use `codex-auth <command>
 | `remove` | [docs/commands/remove.md](./remove.md) |
 | `alias` | [docs/commands/alias.md](./alias.md) |
 | `clean` | [docs/commands/clean.md](./clean.md) |
+| `completion` | [docs/commands/completion.md](./completion.md) |
 | `config` | [docs/commands/config.md](./config.md) |
 
 ## Shared Behavior

docs/commands/completion.md

@@ -0,0 +1,43 @@
+# `codex-auth completion`
+
+## Usage
+
+```shell
+codex-auth completion bash
+codex-auth completion zsh
+codex-auth completion fish
+```
+
+## Bash
+
+`completion bash` prints a Bash completion script to stdout.
+
+Install it with:
+
+```shell
+mkdir -p ~/.local/share/bash-completion/completions
+codex-auth completion bash > ~/.local/share/bash-completion/completions/codex-auth
+```
+
+## Zsh
+
+`completion zsh` prints a Zsh completion script to stdout.
+
+Install it with:
+
+```shell
+mkdir -p ~/.zsh/completions
+codex-auth completion zsh > ~/.zsh/completions/_codex-auth
+```
+
+## Fish
+
+`completion fish` prints a Fish completion script to stdout.
+
+Install it with:
+
+```shell
+mkdir -p ~/.config/fish/completions
+codex-auth completion fish > ~/.config/fish/completions/codex-auth.fish
+source ~/.config/fish/completions/codex-auth.fish
+```

src/cli/commands/completion.zig

@@ -0,0 +1,46 @@
+const std = @import("std");
+const types = @import("../types.zig");
+const common = @import("common.zig");
+
+pub fn parse(allocator: std.mem.Allocator, args: []const [:0]const u8) !types.ParseResult {
+    if (args.len == 1 and common.isHelpFlag(std.mem.sliceTo(args[0], 0))) {
+        return .{ .command = .{ .help = .completion } };
+    }
+    if (args.len == 0) {
+        return common.usageErrorResult(allocator, .completion, "`completion` requires a shell name.", .{});
+    }
+
+    const shell_name = std.mem.sliceTo(args[0], 0);
+    if (args.len == 1) {
+        if (std.mem.eql(u8, shell_name, "bash")) {
+            return .{ .command = .{ .completion = .{ .shell = .bash } } };
+        }
+        if (std.mem.eql(u8, shell_name, "zsh")) {
+            return .{ .command = .{ .completion = .{ .shell = .zsh } } };
+        }
+        if (std.mem.eql(u8, shell_name, "fish")) {
+            return .{ .command = .{ .completion = .{ .shell = .fish } } };
+        }
+    }
+    if (std.mem.eql(u8, shell_name, "query")) {
+        return parseQuery(allocator, args[1..]);
+    }
+    if (args.len > 1) {
+        return common.usageErrorResult(allocator, .completion, "unexpected argument after `completion`: `{s}`.", .{
+            std.mem.sliceTo(args[1], 0),
+        });
+    }
+    return common.usageErrorResult(allocator, .completion, "unknown completion shell `{s}`.", .{shell_name});
+}
+
+fn parseQuery(allocator: std.mem.Allocator, args: []const [:0]const u8) !types.ParseResult {
+    if (args.len != 1) {
+        return common.usageErrorResult(allocator, .completion, "`completion query` requires a target.", .{});
+    }
+
+    const target_name = std.mem.sliceTo(args[0], 0);
+    if (std.mem.eql(u8, target_name, "switch")) {
+        return .{ .command = .{ .completion = .{ .query = .switch_account } } };
+    }
+    return common.usageErrorResult(allocator, .completion, "unknown completion query target `{s}`.", .{target_name});
+}

src/cli/commands/root.zig

@@ -4,6 +4,7 @@ const common = @import("common.zig");
 
 const alias = @import("alias.zig");
 const clean = @import("clean.zig");
+const completion = @import("completion.zig");
 const config = @import("config.zig");
 const export_auth = @import("export.zig");
 const import_auth = @import("import.zig");
@@ -46,6 +47,7 @@ pub fn parseArgs(allocator: std.mem.Allocator, args: []const [:0]const u8) !type
     if (std.mem.eql(u8, cmd, "remove")) return remove.parse(allocator, args[2..]);
     if (std.mem.eql(u8, cmd, "alias")) return alias.parse(allocator, args[2..]);
     if (std.mem.eql(u8, cmd, "clean")) return clean.parse(allocator, args[2..]);
+    if (std.mem.eql(u8, cmd, "completion")) return completion.parse(allocator, args[2..]);
     if (std.mem.eql(u8, cmd, "config")) return config.parse(allocator, args[2..]);
 
     return common.usageErrorResult(allocator, .top_level, "unknown command `{s}`.", .{cmd});
@@ -106,6 +108,7 @@ fn helpTopicForName(name: []const u8) ?types.HelpTopic {
     if (std.mem.eql(u8, name, "remove")) return .remove_account;
     if (std.mem.eql(u8, name, "alias")) return .alias;
     if (std.mem.eql(u8, name, "clean")) return .clean;
+    if (std.mem.eql(u8, name, "completion")) return .completion;
     if (std.mem.eql(u8, name, "config")) return .config;
     return null;
 }