Skip to content

📖 Scribe: Document missing CLI commands in reference #72

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 missing CLI commands in reference #72

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

## 2026-03-05 - Missing CLI Commands in Reference Documentation
**Gap:** Several implemented CLI commands (`connect`, `org-keygen`, `org-sign`, `org-vouch`, `upgrade`) and flags (`--org` for `trust`) were present in `src/main.zig` but missing from `docs/reference/cli.md`.
**Learning:** `src/main.zig` uses hardcoded argument parsing without a central CLI generator, making it easy to add new commands without updating documentation.
**Prevention:** Add a CI check that verifies every command listed in the `usage` string in `src/main.zig` is documented in `docs/reference/cli.md`.
74 changes: 73 additions & 1 deletion docs/reference/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,14 @@ meshguard export > my-node.pub
Add a peer's public key to your authorized keys.

```bash
meshguard trust <key-or-path> [--name <name>]
meshguard trust <key-or-path> [--name <name>] [--org]
```

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

Comment on lines 42 to 47
Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

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

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.

Suggested change
| 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.

Copilot uses AI. Check for mistakes.
**Validation**:

Expand Down Expand Up @@ -117,6 +118,77 @@ meshguard status

---

## `meshguard connect`

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

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

| Flag | Description |
| ------------ | ----------------------------------------------- |
| `--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) |

Copy link

Copilot AI Mar 9, 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 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.

Suggested change
**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.

Copilot uses AI. Check for mistakes.
---

## `meshguard org-keygen`

Generate a new organization keypair.

```bash
meshguard org-keygen
```

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

Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

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

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.

Suggested change
**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`.

Copilot uses AI. Check for mistakes.
---

## `meshguard org-sign`

Sign a node's public key with the organization's private key, producing a NodeCertificate.

```bash
meshguard org-sign <node.pub> [--name <label>] [--expires <unix-timestamp>]
```

| Argument | Description |
| ------------ | ----------------------------------------------- |
| `<node.pub>` | Node's public key file |
| `--name` | Node name label |
Comment on lines +156 to +163
Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

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

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.

Copilot uses AI. Check for mistakes.
| `--expires` | Expiration as a Unix timestamp (default: never) |

---

## `meshguard org-vouch`

Vouch for an external node (auto-propagates to org members).

```bash
meshguard org-vouch <node.pub>
```

| Argument | Description |
| ------------ | ----------------------------------------------- |
| `<node.pub>` | Node's public key file |
Comment on lines +176 to +178
Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

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

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.

Suggested change
| 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) |

Copilot uses AI. Check for mistakes.

---

## `meshguard upgrade`

Upgrade meshguard to the latest release from GitHub.

Copy link

Copilot AI Mar 9, 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 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.

Suggested change
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.

Copilot uses AI. Check for mistakes.
```bash
meshguard upgrade
```

---

## `meshguard version`

Print the version.
Expand Down