Skip to content

Commit 6d3f53f

Browse files
jeffmauryclaude
andcommitted
feat(cli): add generic output formatter to eliminate --output flag duplication
Closes NVIDIA#1750 Creates a new output.rs module with generic helper functions for formatting CLI command output in JSON, YAML, or table formats. This eliminates ~38 lines of duplicated code across 4 commands, provides a single source of truth for output formatting, and makes it easier to add new output formats in the future. Changes: - crates/openshell-cli/src/output.rs: New module with 6 helper functions and 14 tests - crates/openshell-cli/src/lib.rs: Register output module - crates/openshell-cli/src/run.rs: Migrate 4 commands to use helpers - gateway_list(): 23 lines → 5 lines - sandbox_list(): 17 lines → 5 lines - provider_list_profiles(): 12 lines → 7 lines - provider_profile_export(): 11 lines → 8 lines - architecture/cli.md: New CLI architecture documentation - architecture/README.md: Add reference to CLI architecture doc Co-Authored-By: Claude Sonnet 4.5 <[email protected]> Signed-off-by: Jeff MAURY <[email protected]>
1 parent b41e0df commit 6d3f53f

5 files changed

Lines changed: 608 additions & 58 deletions

File tree

‎architecture/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,7 @@ that crate's `README.md`.
161161

162162
| Document | Purpose |
163163
|---|---|
164+
| [CLI](cli.md) | CLI architecture, command implementations, and output formatting patterns. |
164165
| [Gateway](gateway.md) | Gateway control plane, auth, APIs, persistence, settings, and relay coordination. |
165166
| [Sandbox](sandbox.md) | Sandbox supervisor, child process isolation, proxy, credentials, inference, connect, and logs. |
166167
| [Security Policy](security-policy.md) | Policy model, enforcement layers, policy updates, policy advisor, and security logging. |

‎architecture/cli.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# CLI Architecture
2+
3+
The OpenShell CLI (`openshell`) provides a command-line interface for managing sandboxes, gateways, providers, and policies.
4+
5+
## Component Overview
6+
7+
| Component | Path | Purpose |
8+
|-----------|------|---------|
9+
| Main entry point | `crates/openshell-cli/src/main.rs` | CLI argument parsing, command routing |
10+
| Command implementations | `crates/openshell-cli/src/run.rs` | Core command logic |
11+
| Output formatting | `crates/openshell-cli/src/output.rs` | Generic output format helpers |
12+
13+
## Output Formatting
14+
15+
Many CLI commands support the `--output` flag, allowing users to specify output format as JSON, YAML, or table. The `output` module provides generic helper functions to eliminate duplication across commands.
16+
17+
### Design
18+
19+
**Early-return pattern:** Helper functions return `Result<bool>`:
20+
- `Ok(true)` — Format was handled (json/yaml), caller should return immediately
21+
- `Ok(false)` — Format is "table", caller should continue to table rendering
22+
- `Err(e)` — Unsupported format or serialization error
23+
24+
**Available functions:**
25+
26+
- `print_output_collection<T, F>(format, items, to_json)` — Format collections
27+
- `print_output_single<T, F>(format, item, to_json)` — Format single items
28+
- `print_output_direct(format, json_fn, yaml_fn)` — Format pre-formatted strings
29+
- `*_to_writer()` variants — Output to custom writers instead of stdout
30+
31+
### Usage Pattern
32+
33+
```rust
34+
use crate::output::print_output_collection;
35+
36+
pub fn sandbox_list(output: &str) -> Result<()> {
37+
let sandboxes = fetch_sandboxes()?;
38+
39+
// Handle json/yaml output with early return
40+
if print_output_collection(output, &sandboxes, sandbox_to_json)? {
41+
return Ok(());
42+
}
43+
44+
// Fall through to table rendering for "table" format
45+
render_sandbox_table(&sandboxes);
46+
Ok(())
47+
}
48+
49+
fn sandbox_to_json(sandbox: &Sandbox) -> serde_json::Value {
50+
serde_json::json!({
51+
"id": sandbox.id,
52+
"name": sandbox.name,
53+
"status": sandbox.status,
54+
})
55+
}
56+
```
57+
58+
### Behavioral Details
59+
60+
- **JSON output:** Uses `println!()` — includes trailing newline
61+
- **YAML output:** Uses `print!()` — no trailing newline (`serde_yml` includes one)
62+
- **Error handling:** All serialization errors wrapped with `.into_diagnostic()` for miette compatibility
63+
- **Type flexibility:** Format parameter accepts `impl AsRef<str>` for both `&str` and enum types
64+
65+
### Adding Output Support to New Commands
66+
67+
1. Accept an `output: &str` parameter (or use the `OutputFormat` enum from `main.rs`)
68+
2. Write a converter function: `fn item_to_json(item: &Item) -> serde_json::Value`
69+
3. Call the appropriate helper with early-return pattern
70+
4. Implement table rendering for the "table" format
71+
72+
See `gateway_list()` (line 1292) and `sandbox_list()` (line 3166) in `src/run.rs` for examples.
73+
74+
## Commands Using Output Formatting
75+
76+
| Command | Lines | Helper Used | Converter Function |
77+
|---------|-------|-------------|-------------------|
78+
| `gateway list` | ~1290 | `print_output_collection` | `gateway_to_json` |
79+
| `sandbox list` | ~3166 | `print_output_collection` | `sandbox_to_json` |
80+
| `provider list-profiles` | ~4647 | `print_output_direct` | External crate functions |
81+
| `provider profile export` | ~4701 | `print_output_direct` | External crate functions |
82+
83+
Policy commands (`sandbox policy get`, etc.) use writer-based variants for custom output destinations.

‎crates/openshell-cli/src/lib.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ pub mod auth;
1212
pub mod completers;
1313
pub mod edge_tunnel;
1414
pub mod oidc_auth;
15+
pub mod output;
1516
pub(crate) mod policy_update;
1617
pub mod run;
1718
pub mod ssh;

0 commit comments

Comments
 (0)