Skip to content

📖 Scribe: Document meshguard connect command in CLI reference #69

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 in CLI reference #69

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`.

## 2024-05-24 - Missing CLI Command Documentation
**Gap:** The `meshguard connect` command was implemented in `src/main.zig` but missing from the CLI reference in `docs/reference/cli.md`.
**Learning:** The CLI reference document is highly prone to drift because command parsing and help messages are implemented manually in `src/main.zig` rather than using a generator framework.
**Prevention:** Ensure that whenever a new command is added to the `usage` string in `main.zig`, a corresponding section is added to `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 @@ -107,6 +107,23 @@ Uses `RTM_DELLINK` via RTNETLINK to remove the interface.

---

## `meshguard connect`

Direct peer connection via token exchange (bypassing seed nodes) and performs a coordinated UDP hole punch.
Copy link

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

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

The one-line description is grammatically awkward (“... and performs ...”) and reads like two predicates with different subjects. Consider rephrasing to something like “... and perform a coordinated UDP hole punch” or “... performing a coordinated UDP hole punch” for clarity in the CLI reference.

Suggested change
Direct peer connection via token exchange (bypassing seed nodes) and performs a coordinated UDP hole punch.
Establish a direct peer connection via token exchange (bypassing seed nodes) and perform a coordinated UDP hole punch.

Copilot uses AI. Check for mistakes.

Comment on lines +110 to +113
Copy link

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

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

meshguard connect has security/behavioral side effects that aren’t mentioned here: after a successful punch it auto-trusts the peer (adds it to authorized keys) and saves the punched endpoint as a seed in the config directory. The CLI reference should call these out explicitly so users aren’t surprised by persistent config changes.

Copilot uses AI. Check for mistakes.
```bash
meshguard connect --generate [--in <minutes>]
meshguard connect --join <mg://token>
```
Comment on lines +114 to +117
Copy link

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

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

The reference currently omits an important part of the connect flow: in initiator mode (--generate) the command is interactive and prompts the user to paste the peer’s response token back into the initiator terminal. Adding a short “Flow”/“Notes” section (matching the help text in src/main.zig) would make the documented usage complete.

Copilot uses AI. Check for mistakes.

| Flag | Description |
| ------------ | ----------------------------------------------- |
| `--generate` | Generate a connection token as the initiator |
| `--join` | Join a connection using the peer's token |
| `--in` | Delay before punching in minutes (default: 1) |
Comment on lines +119 to +123
Copy link

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

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

The --in flag is documented generically, but in the implementation the joiner uses the punch time embedded in the initiator’s token; changing --in on the joiner side doesn’t affect the scheduled punch time. Consider documenting that --in only applies to the initiator/--generate mode (or clarify how it behaves in --join).

Suggested change
| Flag | Description |
| ------------ | ----------------------------------------------- |
| `--generate` | Generate a connection token as the initiator |
| `--join` | Join a connection using the peer's token |
| `--in` | Delay before punching in minutes (default: 1) |
| Flag | Description |
| ------------ | ---------------------------------------------------------------------------------------------------- |
| `--generate` | Generate a connection token as the initiator |
| `--join` | Join a connection using the peer's token |
| `--in` | Initiator-only: delay before punching in minutes (default: 1); joiner uses the time embedded in the token |

Copilot uses AI. Check for mistakes.

---

## `meshguard status`

Display the current mesh state.
Expand Down