Skip to content

📖 Scribe: Document missing org and upgrade CLI commands #74

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

Open
igorls wants to merge 1 commit into
base: main
Choose a base branch
from
Open

📖 Scribe: Document missing org and upgrade CLI commands #74

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
4 changes: 4 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,7 @@
**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`.
Copy link

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

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

There’s no blank line separating this new section from the previous one (the earlier entries are separated by a blank line). Consider adding an empty line before this heading for consistent Markdown formatting/readability.

Suggested change
**Prevention:** Add a CI check that grep's `docs/guide/configuration.md` for values that match constants exported in `src/config.zig`.
**Prevention:** Add a CI check that grep's `docs/guide/configuration.md` for values that match constants exported in `src/config.zig`.

Copilot uses AI. Check for mistakes.
## 2026-03-10 - Manual CLI Drift
**Gap:** The org-keygen, org-sign, org-vouch, and upgrade commands were completely missing from docs/reference/cli.md despite existing in src/main.zig.
**Learning:** Because CLI argument parsing and help messages in src/main.zig are implemented manually rather than using a generator framework, the CLI reference documentation (docs/reference/cli.md) is highly prone to drift if not updated concurrently.
**Prevention:** We need to habitually check the fn main() switch cases or the usage string block in src/main.zig whenever updating CLI docs to ensure no commands have been added without corresponding documentation updates.
Copy link

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

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

This entry says to check “fn main() switch cases”, but src/main.zig dispatches commands via an if (std.mem.eql(...)) chain (no switch). Please reword this to match the actual structure so the prevention guidance is actionable.

Suggested change
**Prevention:** We need to habitually check the fn main() switch cases or the usage string block in src/main.zig whenever updating CLI docs to ensure no commands have been added without corresponding documentation updates.
**Prevention:** We need to habitually check the `if (std.mem.eql(...))` command-dispatch chain and the usage/help string block in src/main.zig whenever updating CLI docs to ensure no commands have been added without corresponding documentation updates.

Copilot uses AI. Check for mistakes.
55 changes: 55 additions & 0 deletions docs/reference/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -243,3 +243,58 @@ meshguard connect --join mg://...
| Variable | Description |
| ---------------------- | ---------------------------------------------------------- |
| `MESHGUARD_CONFIG_DIR` | Override config directory (default: `~/.config/meshguard`) |

---

## `meshguard org-keygen`

Generate a new Ed25519 organization keypair.

```bash
meshguard org-keygen
```

**Output files** (in `$MESHGUARD_CONFIG_DIR`):

- `org.key` — secret key (permissions `0600`)
- `org.pub` — public key
Comment on lines +257 to +260
Copy link

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

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

The org keypair files are saved under $MESHGUARD_CONFIG_DIR/org/ (see Org.saveOrgKeyPair / loadOrgKeyPair), not directly in $MESHGUARD_CONFIG_DIR. Please update the output paths accordingly to avoid pointing users at the wrong location.

Suggested change
**Output files** (in `$MESHGUARD_CONFIG_DIR`):
- `org.key` — secret key (permissions `0600`)
- `org.pub` — public key
**Output files** (in `$MESHGUARD_CONFIG_DIR/org/`):
- `org/org.key` — secret key (permissions `0600`)
- `org/org.pub` — public key

Copilot uses AI. Check for mistakes.

---

## `meshguard org-sign`

Sign a node's public key with the organization key.

```bash
meshguard org-sign <node-key-or-path> [--name <label>] [--expires <unix-timestamp>]
```

| Argument | Description |
| -------- | ----------- |
| `<node-key-or-path>` | Base64 public key string _or_ path to a `.pub` file |
| `--name` | Human-readable name for the node |
| `--expires` | Unix timestamp when the signature expires (default: 0, never expires) |

---

## `meshguard org-vouch`

Vouch for an external node. This action auto-propagates to organization members.

```bash
meshguard org-vouch <node-key-or-path>
```

| Argument | Description |
| -------- | ----------- |
| `<node-key-or-path>` | Base64 public key string _or_ path to a `.pub` file |

---

## `meshguard upgrade`

Upgrade meshguard to the latest release from GitHub.

```bash
meshguard upgrade
```
Comment on lines +294 to +300
Copy link

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

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

meshguard upgrade is implemented as a Linux/systemd-specific self-updater: it downloads the meshguard-linux-amd64 asset, uses systemctl to stop/start the service, and installs to /usr/local/bin/meshguard (often requiring sudo). The docs currently describe it generically; please document these OS/arch and privilege/tooling requirements so users on other platforms don’t assume it will work.

Copilot uses AI. Check for mistakes.