diff --git a/.tasks/backlog/2026-02-18-cli-docs-audit.md b/.tasks/done/2026-02-18-cli-docs-audit.md similarity index 70% rename from .tasks/backlog/2026-02-18-cli-docs-audit.md rename to .tasks/done/2026-02-18-cli-docs-audit.md index 635f06aa..c77ff8d1 100644 --- a/.tasks/backlog/2026-02-18-cli-docs-audit.md +++ b/.tasks/done/2026-02-18-cli-docs-audit.md @@ -1,6 +1,6 @@ --- title: Audit CLI commands and docs for consistency -status: backlog +status: done created: 2026-02-18 updated: 2026-02-18 --- @@ -28,3 +28,15 @@ updated but there may be inconsistencies remaining. - The label-based routing feature changed target syntax and added hierarchical labels — make sure all references use the new format - Check for any stale references to old flat label syntax (e.g., `role:web`) + +## Outcome + +Added `-T, --target` flag documentation to 5 CLI doc files: + +- `system/hostname.md` — added new Flags section +- `system/status.md` — added new Flags section +- `network/dns/get.md` — added row to existing Flags table +- `network/dns/update.md` — added row to existing Flags table +- `network/ping/ping.md` — added row to existing Flags table + +No stale label syntax found; all examples already use hierarchical format. diff --git a/docs/docs/sidebar/api-guidelines.md b/docs/docs/sidebar/api-guidelines.md index 27c540dc..9fff93e0 100644 --- a/docs/docs/sidebar/api-guidelines.md +++ b/docs/docs/sidebar/api-guidelines.md @@ -4,34 +4,26 @@ sidebar_position: 6 # API Design Guidelines -1. **General System Information or Status** - -- **Path**: `/system/` -- **Description**: Endpoints that represent broader operations impacting the - entire system, such as system status or information, should stay under - `/system/`. -- **Examples**: - - `/system/status` - - `/system/info` - -2. **Functional Areas** - -Functional areas like power management, NTP, or network management should be -broken into separate categories if they involve multiple endpoints or represent -distinct areas of configuration. - -- Examples: - - **Power Management**: - - `/power/` - Power-related operations (shutdown, reboot, hibernate). - - **NTP Management**: - - `/ntp/` - NTP settings management. - - `/ntp/sync` - Time synchronization with NTP servers. - - **Network Management**: - - `/network/` - Network interfaces, routes, and DNS management. - -3. **Consider Scalability and Future Needs** - -If an area is expected to grow in complexity with more endpoints, it's best to -separate it early into its own category, even if it only has a few operations -today. This ensures future scalability and avoids clutter in the core `/system/` -path. +1. **Top-Level Categories** + +Group endpoints by functional domain. Each domain gets its own top-level path +prefix (e.g., `/system/`, `/network/`, `/job/`). Avoid nesting unrelated +operations under a shared prefix. + +2. **Resource-Oriented Paths** + +Use nouns for resources and let HTTP methods convey the action. Sub-resources +should be nested under their parent (e.g., `/network/dns/{interfaceName}`). + +3. **Consistent Verb Mapping** + +- `GET` — Read or list resources +- `POST` — Create a resource or trigger an action +- `PUT` — Replace or update a resource +- `DELETE` — Remove a resource + +4. **Scalability and Future Needs** + +If an area is expected to grow in complexity with more endpoints, separate it +into its own top-level category early — even if it only has a few operations +today. This avoids clutter and keeps each domain cohesive. diff --git a/docs/docs/sidebar/usage/cli/client/network/dns/get.md b/docs/docs/sidebar/usage/cli/client/network/dns/get.md index 5f9a60fd..2d1aa0ea 100644 --- a/docs/docs/sidebar/usage/cli/client/network/dns/get.md +++ b/docs/docs/sidebar/usage/cli/client/network/dns/get.md @@ -33,6 +33,7 @@ $ osapi client network dns get --interface-name eth0 --target group:web ## Flags -| Flag | Description | Default | -| ------------------ | ---------------------------------------------- | -------- | -| `--interface-name` | Name of the network interface to query DNS for | required | +| Flag | Description | Default | +| ------------------ | -------------------------------------------------------- | -------- | +| `--interface-name` | Name of the network interface to query DNS for | required | +| `-T, --target` | Target: `_any`, `_all`, hostname, or label (`group:web`) | `_any` | diff --git a/docs/docs/sidebar/usage/cli/client/network/dns/update.md b/docs/docs/sidebar/usage/cli/client/network/dns/update.md index 509d3647..45415410 100644 --- a/docs/docs/sidebar/usage/cli/client/network/dns/update.md +++ b/docs/docs/sidebar/usage/cli/client/network/dns/update.md @@ -44,10 +44,11 @@ $ osapi client network dns update \ ## Flags -| Flag | Description | Default | -| ------------------ | ---------------------------------------------- | -------- | -| `--servers` | List of DNS server IP addresses | one of\* | -| `--search-domains` | List of DNS search domains | one of\* | -| `--interface-name` | Name of the network interface to configure DNS | required | +| Flag | Description | Default | +| ------------------ | -------------------------------------------------------- | -------- | +| `--servers` | List of DNS server IP addresses | one of\* | +| `--search-domains` | List of DNS search domains | one of\* | +| `--interface-name` | Name of the network interface to configure DNS | required | +| `-T, --target` | Target: `_any`, `_all`, hostname, or label (`group:web`) | `_any` | \*At least one of `--servers` or `--search-domains` must be provided. diff --git a/docs/docs/sidebar/usage/cli/client/network/ping/ping.md b/docs/docs/sidebar/usage/cli/client/network/ping/ping.md index 3d7ccd1b..edd85891 100644 --- a/docs/docs/sidebar/usage/cli/client/network/ping/ping.md +++ b/docs/docs/sidebar/usage/cli/client/network/ping/ping.md @@ -37,6 +37,7 @@ $ osapi client network ping --address 8.8.8.8 --target group:web ## Flags -| Flag | Description | Default | -| --------------- | ------------------- | -------- | -| `-a, --address` | The address to ping | required | +| Flag | Description | Default | +| --------------- | -------------------------------------------------------- | -------- | +| `-a, --address` | The address to ping | required | +| `-T, --target` | Target: `_any`, `_all`, hostname, or label (`group:web`) | `_any` | diff --git a/docs/docs/sidebar/usage/cli/client/system/hostname.md b/docs/docs/sidebar/usage/cli/client/system/hostname.md index ec4e0936..1c9226d8 100644 --- a/docs/docs/sidebar/usage/cli/client/system/hostname.md +++ b/docs/docs/sidebar/usage/cli/client/system/hostname.md @@ -30,3 +30,9 @@ Target by label to query a group of servers: ```bash $ osapi client system hostname --target group:web ``` + +## Flags + +| Flag | Description | Default | +| -------------- | -------------------------------------------------------- | ------- | +| `-T, --target` | Target: `_any`, `_all`, hostname, or label (`group:web`) | `_any` | diff --git a/docs/docs/sidebar/usage/cli/client/system/status.md b/docs/docs/sidebar/usage/cli/client/system/status.md index f21a184f..7063a91b 100644 --- a/docs/docs/sidebar/usage/cli/client/system/status.md +++ b/docs/docs/sidebar/usage/cli/client/system/status.md @@ -40,3 +40,9 @@ Target by label to query a group of servers: $ osapi client system status --target group:web $ osapi client system status --target group:web.dev ``` + +## Flags + +| Flag | Description | Default | +| -------------- | -------------------------------------------------------- | ------- | +| `-T, --target` | Target: `_any`, `_all`, hostname, or label (`group:web`) | `_any` |