📖 Scribe: Document meshguard connect command in CLI reference#69
📖 Scribe: Document meshguard connect command in CLI reference#69
Conversation
This commit adds the `meshguard connect` command and its flags (`--generate`, `--join`, `--in`) to the `docs/reference/cli.md` file. This command was implemented in `src/main.zig` but was missing from the documentation. Co-authored-by: igorls <4753812+igorls@users.noreply.github.com>
|
👋 Jules, reporting for duty! I'm here to lend a hand with this pull request. When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down. I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job! For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with New to Jules? Learn more at jules.google/docs. For security, I will only act on instructions from the user who triggered this task. |
There was a problem hiding this comment.
Pull request overview
Adds missing CLI reference documentation for meshguard connect, based on the src/main.zig usage/help text, and records the doc-drift learning in .jules/scribe.md.
Changes:
- Documented
meshguard connectindocs/reference/cli.md, including--generate,--join, and--in. - Added a new “learning” entry to
.jules/scribe.mdabout manual CLI parsing causing documentation drift.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/reference/cli.md | Adds a new section describing the meshguard connect command, examples, and flags. |
| .jules/scribe.md | Adds a scribe entry capturing the documentation gap and a prevention note. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ## `meshguard connect` | ||
|
|
||
| Direct peer connection via token exchange (bypassing seed nodes) and performs a coordinated UDP hole punch. |
There was a problem hiding this comment.
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.
| 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. |
| ```bash | ||
| meshguard connect --generate [--in <minutes>] | ||
| meshguard connect --join <mg://token> | ||
| ``` |
There was a problem hiding this comment.
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.
| ## `meshguard connect` | ||
|
|
||
| Direct peer connection via token exchange (bypassing seed nodes) and performs a coordinated UDP hole punch. | ||
|
|
There was a problem hiding this comment.
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.
| | 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) | |
There was a problem hiding this comment.
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).
| | 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 | |
|
Closing: superseded by docs audit fixes and direct commits to main. See PR #67 (merged) for codec bounds check, and direct commit for timing-safe fix in noise.zig. |
What: The
meshguard connectcommand was missing from the CLI reference documentation (docs/reference/cli.md).Source:
src/main.zigusage string and command parser block.Fix: Added the
meshguard connectcommand documentation, including its specific flags (--generate,--join,--in), todocs/reference/cli.md. Also appended a learning entry in.jules/scribe.mdregarding manual CLI argument parsing causing drift.PR created automatically by Jules for task 15735611632967095827 started by @igorls