osapi-io · retr0h · Feb 18, 2026 · Feb 18, 2026
diff --git a/.tasks/backlog/2026-02-18-cli-docs-audit.md → .tasks/done/2026-02-18-cli-docs-audit.md b/.tasks/backlog/2026-02-18-cli-docs-audit.md → .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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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`  |