From c38d9aea99650b4e0e49f412c6cfd6f603b77119 Mon Sep 17 00:00:00 2001
From: DualFroz <me@dualfroz.com>
Date: Thu, 23 Jul 2026 07:25:45 +0200
Subject: [PATCH] docs+fix: document auth subcommands; enforce
 --no-external/--external
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docs/cli.md called itself the 'complete non-interactive surface' but
never listed vulp auth add/remove/switch/test (only import) — real,
script-usable subcommands with zero documentation. Also documented
the missing --allow-secrets flag on the sync synopsis line. Separately,
'list --no-external --external' together silently returned an
always-empty result (two independent retain passes) instead of an
error; now rejected as a usage error (exit 2), matching what the
synopsis's '|' already implied.
---
 docs/cli.md               | 17 ++++++++++++++++-
 src/cli_cmds/workspace.rs |  3 +++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/docs/cli.md b/docs/cli.md
index 4c50bef..1521ae4 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -110,7 +110,7 @@ Both empty (the default) disables the feature entirely — no SSH attempted.
 ## Git operations
 
 ```
-vulp sync <repo>... [--action pull|push|commit-push] [-m MSG]
+vulp sync <repo>... [--action pull|push|commit-push] [-m MSG] [--allow-secrets]
 vulp sync --all --action pull
 vulp sync --project NAME --action push
 vulp release <repo> --tag v1.2.0 [--notes "..."]   # git tag + push + provider release
@@ -157,6 +157,21 @@ vulp accounts [--json]
 `pr/issue list` read the on-disk cache (`~/.vulp/`) — the same one the TUI
 uses; run `vulp refresh` first when freshness matters.
 
+## Auth (non-interactive account management)
+
+```
+vulp auth import                                        # import from `gh` CLI, no token needed
+vulp auth add --provider github --token ghp_xxx [--alias work] [--url https://...]
+vulp auth remove <account>                               # <account> = provider/alias, e.g. github/work
+vulp auth switch <account>                               # change which account is the default
+vulp auth test [<account>]                                # verify a token still works, print a preview
+```
+
+`--url` is for self-hosted GitLab/Gitea instances; omit it for github.com/gitlab.com.
+Every subcommand here is fully non-interactive (no prompts) and usable from
+scripts/CI without ever touching `gh` — `vulp auth import` is the convenience
+path when `gh` is already authenticated, `add` is the direct path when it isn't.
+
 ## Per-repo utilities
 
 ```
diff --git a/src/cli_cmds/workspace.rs b/src/cli_cmds/workspace.rs
index b215fe4..000bd6b 100644
--- a/src/cli_cmds/workspace.rs
+++ b/src/cli_cmds/workspace.rs
@@ -12,6 +12,9 @@ pub fn list(
     lang: Option<String>, project: Option<String>, alerts: bool, stale_deploy: bool,
     no_external: bool, external: bool,
 ) -> Result<()> {
+    if no_external && external {
+        die(2, "--no-external and --external are mutually exclusive");
+    }
     let mut repos = scan_repos(cfg);
 
     if dirty  { repos.retain(|r| r.is_dirty); }