Skip to content

📖 Scribe: Document meshguard connect command #66

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
igorls wants to merge 1 commit into from
Closed

📖 Scribe: Document meshguard connect command #66

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .jules/scribe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,8 @@
**Gap:** The documentation stated the SWIM protocol period was 1000ms (1s), but the implementation uses 5000ms (5s) in both `src/config.zig` and `src/discovery/swim.zig`.
**Learning:** The documentation likely reflected an early design decision or standard SWIM defaults, but the implementation settled on a more conservative 5s interval for WAN stability, and docs were not updated.
**Prevention:** Add a CI check that grep's `docs/guide/configuration.md` for values that match constants exported in `src/config.zig`.

## 2025-02-13 - Missing CLI Command Documentation
Copy link

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The journal entry date 2025-02-13 appears to be inaccurate. The current date is March 2026, and the previous scribe entry is dated 2026-02-24. This new entry is dated about a year earlier than that entry, placing it out of chronological order in the file. The date should reflect when this documentation gap was identified and fixed (approximately 2026-03-07 or similar).

Suggested change
## 2025-02-13 - Missing CLI Command Documentation
## 2026-03-07 - Missing CLI Command Documentation

Copilot uses AI. Check for mistakes.
**Gap:** The CLI reference documentation `docs/reference/cli.md` was missing several commands that are fully implemented and functional in `src/main.zig`, most notably `meshguard connect`.
**Learning:** `src/main.zig` implements manual argument parsing and does not use a generator framework, making the CLI reference highly prone to drift if not updated concurrently.
**Prevention:** Periodically run a script to cross-reference all commands listed in `src/main.zig`'s usage text against the headers in `docs/reference/cli.md`.
17 changes: 17 additions & 0 deletions docs/reference/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,23 @@ meshguard up [options]

---

## `meshguard connect`

Direct peer connection via token exchange (bypassing seed nodes). Enables coordinated UDP hole punching for peers behind NAT.

```bash
meshguard connect --generate [--in <minutes>]
meshguard connect --join <mg://token>
```

| Flag | Description |
| ------------ | -------------------------------------------------- |
| `--generate` | Generate a connection token (initiator) |
| `--in` | Delay in minutes before punching (default: 1) |
| `--join` | Join a connection using the peer's `mg://` token |

Copy link

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The meshguard connect command involves a mandatory two-step interactive protocol between two peers that is not documented here. Users need to know:

  1. The initiator runs --generate, then shares the printed mg:// token with the peer
  2. The peer runs --join <token>, then pastes the response token back to the initiator
  3. Both sides then punch simultaneously

This is consistent with how meshguard up documents its "Startup sequence" as a numbered list. Without this flow description, users may not understand that --generate is interactive (it reads from stdin) or that there is a required back-and-forth token exchange between the two parties.

Suggested change
**Connection sequence**:
1. Initiator runs `meshguard connect --generate [--in <minutes>]` and is printed an `mg://` token.
2. Initiator securely shares this `mg://` token with the peer.
3. Peer runs `meshguard connect --join <mg://token>`, which prints a response token.
4. Peer sends the response token back to the initiator.
5. Initiator pastes the response token into the waiting `--generate` process (stdin).
6. At the agreed time (controlled by `--in`), both sides punch simultaneously to establish the direct connection.

Copilot uses AI. Check for mistakes.
---

## `meshguard down`

Stop the daemon and remove the `mg0` interface.
Expand Down