From 7c24351f4ac53dd23aa95722649cd3529894d6ee Mon Sep 17 00:00:00 2001
From: "E. Kaparulin" <e.kaparulin@gmail.com>
Date: Wed, 30 Sep 2026 11:59:41 +0300
Subject: [PATCH] fix: correct the CLI examples for --use-proxy and
 --listen-socks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both sections showed

  ./konduit connect --config client.toml --use-proxy ...

which cannot work. `--config` is declared on the top-level Args struct,
while `--use-proxy` and `--listen-socks` belong to the `connect`
subcommand, so clap rejects the combination outright:

  $ konduit connect --config client.toml --use-proxy socks5://...
  error: unexpected argument '--config' found
  $ konduit --config client.toml --use-proxy socks5://...
  error: unexpected argument '--use-proxy' found

Neither ordering works — an invocation has to pick one style: config file
(everything from the file) or `connect` subcommand (everything as flags).
Replaced with the full flag form and said so explicitly, since "or via the
CLI" read as though you could bolt a flag onto a config-file run.

Both replacement command lines were run against the built binary to
confirm they parse; they get as far as the connection attempt.
---
 docs/socks-modes.md | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/docs/socks-modes.md b/docs/socks-modes.md
index 53f266e..ee7e6cd 100644
--- a/docs/socks-modes.md
+++ b/docs/socks-modes.md
@@ -14,12 +14,19 @@ server_endpoint = "vpn.example.com:443"
 use_proxy       = "socks5://127.0.0.1:1080"
 ```
 
-Or via the CLI:
+Or, if you are passing everything on the command line rather than via a config file:
 
 ```bash
-./konduit connect --config client.toml --use-proxy socks5://127.0.0.1:1080
+./konduit connect \
+  --server vpn.example.com:443 \
+  --peer-id "$PEER_ID" \
+  --identity "$IDENTITY_HEX" \
+  --server-pub "$SERVER_PUB_HEX" \
+  --use-proxy socks5://127.0.0.1:1080
 ```
 
+`--config` and `--use-proxy` cannot be combined. `--config` is a top-level flag, while `--use-proxy` belongs to the `connect` subcommand, so a single invocation has to pick one style. Mixing them fails with `error: unexpected argument '--use-proxy' found`.
+
 Konduit dials the SOCKS5 proxy, asks it to `CONNECT` to your server, and then runs its normal protocol over that connection — the proxy is otherwise transparent to it. If the proxy is unreachable, or requires authentication konduit doesn't support, the connection attempt fails immediately; there is no silent fallback to a direct connection.
 
 ## Listener: exposing a SOCKS5 proxy after the tunnel is up (`listen_socks`)
@@ -31,10 +38,15 @@ Once connected, konduit can also expose a local SOCKS5 listener so other tools (
 listen_socks = "127.0.0.1:1080"
 ```
 
-Or via the CLI:
+Or via the `connect` subcommand, as above — `--listen-socks` takes a bare address:
 
 ```bash
-./konduit connect --config client.toml --listen-socks 127.0.0.1:1080
+./konduit connect \
+  --server vpn.example.com:443 \
+  --peer-id "$PEER_ID" \
+  --identity "$IDENTITY_HEX" \
+  --server-pub "$SERVER_PUB_HEX" \
+  --listen-socks 127.0.0.1:1080
 ```
 
 Connections accepted by the listener are plain outbound TCP connections, routed through the tunnel by the kernel's routing table — the same routes any other tunnelled traffic uses. The SOCKS code itself has no VPN-specific logic.