📖 Scribe: Document missing CLI commands in reference#72
Conversation
Updated `docs/reference/cli.md` to properly document several commands and flags that are implemented in `src/main.zig` but were missing from the reference documentation. What: - Added `--org` flag under the `meshguard trust` section. - Added documentation for `connect`, `org-keygen`, `org-sign`, `org-vouch`, and `upgrade` commands. - Appended learning to `.jules/scribe.md` to track CLI argument drift. Source: `src/main.zig` Fix: Added markdown sections in `docs/reference/cli.md` for missing features. 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
Updates the CLI reference documentation to cover commands and flags already implemented in src/main.zig, reducing drift between the actual CLI surface and the published docs.
Changes:
- Documented
meshguard connect,org-keygen,org-sign,org-vouch, andupgradeindocs/reference/cli.md. - Added the
--orgflag to themeshguard trustreference section. - Recorded the “CLI arg drift” learning/prevention note in
.jules/scribe.md.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| docs/reference/cli.md | Adds missing CLI command/flag sections to the reference docs. |
| .jules/scribe.md | Adds a new “scribe” entry describing the doc drift and a proposed CI prevention check. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ```bash | ||
| meshguard org-sign <node.pub> [--name <label>] [--expires <unix-timestamp>] | ||
| ``` | ||
|
|
||
| | Argument | Description | | ||
| | ------------ | ----------------------------------------------- | | ||
| | `<node.pub>` | Node's public key file | | ||
| | `--name` | Node name label | |
There was a problem hiding this comment.
meshguard org-sign accepts either a base64 public key string or a path to a .pub file (it uses the same key-or-path validation as trust). The docs currently imply only a file input (<node.pub>); consider updating the argument name/description to reflect the accepted forms.
| | Argument | Description | | ||
| | ------------ | ----------------------------------------------- | | ||
| | `<node.pub>` | Node's public key file | |
There was a problem hiding this comment.
meshguard org-vouch also accepts either a base64 public key string or a path to a .pub file (via the shared key-or-path validator). The docs currently state only a file argument; consider updating the argument description to match the implementation.
| | Argument | Description | | |
| | ------------ | ----------------------------------------------- | | |
| | `<node.pub>` | Node's public key file | | |
| | Argument | Description | | |
| | ------------ | --------------------------------------------------------------- | | |
| | `<node.pub>` | Node's public key (path to `.pub` file or base64-encoded key) | |
| ## `meshguard upgrade` | ||
|
|
||
| Upgrade meshguard to the latest release from GitHub. | ||
|
|
There was a problem hiding this comment.
meshguard upgrade is implemented in a Linux/systemd-centric way (uses curl, systemctl, and installs to /usr/local/bin/meshguard, typically requiring sudo). The docs currently read as generally applicable; consider documenting OS/prerequisite/permission requirements (and/or limitations) to prevent confusion on non-Linux or non-systemd setups.
| This command is implemented for Linux environments where `systemd` is available. It: | |
| - uses tools such as `curl` and `systemctl` | |
| - installs or replaces the binary at `/usr/local/bin/meshguard` | |
| - typically requires `sudo` or equivalent privileges to succeed | |
| On non-Linux or non-systemd systems, or where you do not have sufficient permissions, | |
| this command may not work as expected; use your platform's installation/upgrade | |
| method instead. |
| | Argument | Description | | ||
| | --------------- | ------------------------------------------------------ | | ||
| | `<key-or-path>` | Base64 public key string _or_ path to a `.pub` file | | ||
| | `--name` | Human-readable name (default: auto-generated from key) | | ||
| | `--org` | Trust an organization's public key | | ||
|
|
There was a problem hiding this comment.
The meshguard trust docs list --name as “auto-generated from key”, but when --org is used the implementation defaults the org name to a derived domain (and --name becomes an org alias override). Consider clarifying --name behavior for --org vs peer trust so users don’t assume the same naming rules apply.
| | Argument | Description | | |
| | --------------- | ------------------------------------------------------ | | |
| | `<key-or-path>` | Base64 public key string _or_ path to a `.pub` file | | |
| | `--name` | Human-readable name (default: auto-generated from key) | | |
| | `--org` | Trust an organization's public key | | |
| | Argument | Description | | |
| | --------------- | ----------------------------------------------------------------------------------------------------- | | |
| | `<key-or-path>` | Base64 public key string _or_ path to a `.pub` file | | |
| | `--name` | For peer keys: human-readable name (default: auto-generated from key). With `--org`: org alias/label | | |
| | `--org` | Trust an organization's public key (org name derived from key's domain unless overridden by `--name`)| | |
| **Note**: When using `--org`, the organization name is derived from the key's domain by default. Supplying `--name` does **not** change this derivation logic; it only overrides the displayed organization label in your local trust store. |
| | `--generate` | Generate a token to share with the peer | | ||
| | `--join` | Join a connection using the peer's token | | ||
| | `--in` | Punch delay in minutes (default: 1 minute) | | ||
|
|
There was a problem hiding this comment.
The meshguard connect command has important side effects in the implementation (it auto-adds the peer to authorized_keys and saves the punched endpoint as a seed in the config). Consider documenting these behaviors in this section so users understand the trust/security and persistence implications of running connect.
| **Side effects & security** | |
| - On successful connection, the peer's public key is automatically added to your `authorized_keys`. Only use `connect` with tokens from peers you trust to grant ongoing access. | |
| - The discovered/punched endpoint is saved into your config as a persistent seed. This means the peer may be used for future bootstrap and reconnection until you remove or edit that seed entry. |
| **Output files** (in `$MESHGUARD_CONFIG_DIR/org/`): | ||
| - `org.key` — secret key | ||
| - `org.pub` — public key | ||
|
|
There was a problem hiding this comment.
meshguard org-keygen exits with an error if an org keypair already exists. It would be helpful to mention this “refuses to overwrite existing keys” behavior (and what users should do if they need to rotate/regenerate keys), since the command is not safely re-runnable.
| **Safety**: Refuses to overwrite existing organization keys; if `org.key` / `org.pub` already exist, the command exits with an error. To rotate or regenerate the organization keypair, back up or remove the existing files in `$MESHGUARD_CONFIG_DIR/org/` and then rerun `meshguard org-keygen`. |
|
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. |
Understood. Acknowledging that this work is now obsolete and stopping work on this task. |
Updated
docs/reference/cli.mdto properly document several commands and flags that are implemented insrc/main.zigbut were missing from the reference documentation.What:
--orgflag under themeshguard trustsection.connect,org-keygen,org-sign,org-vouch, andupgradecommands..jules/scribe.mdto track CLI argument drift.Source:
src/main.zigFix: Added markdown sections in
docs/reference/cli.mdfor missing features.PR created automatically by Jules for task 12139278353924132439 started by @igorls