Skip to content

Commit c77b34a

Browse files
aviatcoAviat Cohen
aviatco
and
Aviat Cohen
authored
docs: Add doc for output format (#122)
Co-authored-by: Aviat Cohen <aviatcohen@microsoft.com>
1 parent 7b148f5 commit c77b34a

2 files changed

Lines changed: 272 additions & 0 deletions

File tree

‎docs/essentials/output_format.md‎

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
# Output Format - User Guide
2+
3+
The Fabric CLI provides flexible output formatting options to support both human-readable and machine-parseable results. This guide covers how to configure and use output formats effectively.
4+
5+
## Overview
6+
7+
The output format feature allows you to control how command results are displayed. The CLI supports two primary output formats:
8+
- **Text Format** (default): Human-readable, formatted output optimized for terminal viewing
9+
- **JSON Format**: Structured, machine-parseable output suitable for scripting and automation
10+
11+
## Supported Output Formats
12+
13+
### Text Format (`text`)
14+
The default format that provides human-readable output with:
15+
- Clean, formatted display
16+
- Headers for tabular data when using `-l` or `-q` flags
17+
- Color-coded status indicators
18+
- Progress indicators and informational messages
19+
- Unix-style listings for directory-like commands
20+
21+
### JSON Format (`json`)
22+
Structured output format that provides:
23+
- Consistent JSON schema across all commands
24+
- Machine-parseable results
25+
- Standardized error reporting
26+
- Timestamp and command metadata
27+
28+
## Configuration
29+
30+
### Command-Line Flag
31+
Override the output format for any command using the global `--output_format` flag:
32+
33+
```bash
34+
# Use JSON format for a single command
35+
fab ls --output_format json
36+
37+
# Use text format explicitly
38+
fab auth status --output_format text
39+
```
40+
41+
**Available Values:**
42+
- `json` - JSON structured output
43+
- `text` - Human-readable text output (default)
44+
45+
### Configuration File
46+
Set the default output format using the [`fab config set`](../examples/config_examples.md) command:
47+
48+
```bash
49+
# Set JSON as default format
50+
fab config set output_format json
51+
52+
# Set text as default format (default)
53+
fab config set output_format text
54+
55+
# View current setting
56+
fab config get output_format
57+
```
58+
59+
The configuration is stored in your Fabric CLI configuration file and applies to all subsequent commands unless overridden by the `--output_format` flag.
60+
61+
## JSON Output Schema
62+
63+
### Success Response Structure
64+
```json
65+
{
66+
"timestamp": "2026-01-06T08:00:00.000Z",
67+
"status": "Success",
68+
"command": "command_name",
69+
"result": {
70+
"data": [
71+
{
72+
"id": "example-id",
73+
"name": "example-name",
74+
"type": "example-type"
75+
}
76+
],
77+
"hidden_data": [
78+
".capacities",
79+
".gateways"
80+
],
81+
"message": "Operation completed successfully"
82+
}
83+
}
84+
```
85+
86+
### Error Response Structure
87+
```json
88+
{
89+
"timestamp": "2026-01-06T08:00:00.000Z",
90+
"status": "Failure",
91+
"command": "command_name",
92+
"result": {
93+
"message": "Unable to find workspace: workspace1",
94+
"error_code": "ERROR_WORKSPACE_NOT_FOUND"
95+
}
96+
}
97+
```
98+
99+
### JSON Schema Fields
100+
101+
#### Root Level
102+
- **`timestamp`** (string): ISO 8601 UTC timestamp when the command completed
103+
- **`status`** (string): Either `"Success"` or `"Failure"`
104+
- **`command`** (string, optional): The primary command that was executed
105+
- **`result`** (object): Contains the actual command results
106+
107+
#### Result Object
108+
- **`data`** (array, optional): Primary output data when available
109+
- **`hidden_data`** (array, optional): Virtual workspace items like capacities, gateways, managed private endpoints etc...
110+
- **`message`** (string, optional): Success message or operation description
111+
- **`error_code`** (string, optional): Standardized error code (only present on failures)
112+
113+
## Text Output Behavior
114+
115+
### Success Output
116+
Text format provides context-aware formatting:
117+
118+
```bash
119+
# Basic directory listing (names only)
120+
$ fab ls
121+
workspace1
122+
workspace2
123+
124+
# Directory listing with details (-l flag)
125+
$ fab ls -l
126+
name id capacityName capacityId capacityRegion
127+
---------------------------------------------------------------------------------------------------------------------
128+
workspace1 12345678-1234-1234-1234-123456789012 MyCapacity 87654321-4321-4321-4321-210987654321 East US
129+
workspace2 12345678-1234-1234-1234-123456789013 MyCapacity 87654321-4321-4321-4321-210987654321 East US
130+
131+
# Simple success message
132+
$ fab auth logout
133+
* Logged out of Fabric account
134+
135+
# Data with message (mkdir shows table by default)
136+
$ fab mkdir workspace1
137+
* 'workspace1' created
138+
```
139+
140+
### Error Output
141+
Error messages include the error code in brackets followed by the message:
142+
143+
```bash
144+
$ fab ls invalid-workspace
145+
x ls: [NotFound] The Workspace 'invalid-workspace.Workspace' could not be found
146+
```
147+
148+
### Informational Output
149+
Informational messages (warnings, progress, debug info) are always sent to `stderr` regardless of output format:
150+
151+
```bash
152+
$ fab mv ws1.Workspace/r1.Report ws1.Workspace/
153+
Moving '/ws.Workspace/r1.Report' → '/ws1.Workspace/r1.Report'...
154+
* Move completed
155+
```
156+
157+
## Stream Behavior
158+
159+
### Standard Output (stdout)
160+
- **All command results** (both success and error responses)
161+
- **JSON format**: All JSON responses
162+
- **Text format**: Command results, data, and final status messages
163+
164+
### Standard Error (stderr)
165+
- Warning messages
166+
- Informational messages
167+
- Debug messages
168+
- Progress indicators
169+
170+
This separation allows you to:
171+
- Redirect command results to files while preserving interactive feedback
172+
- Filter informational messages separately from actual data
173+
- Pipe JSON output to processing tools without interference
174+
175+
## Usage Examples
176+
177+
### Basic Usage
178+
```bash
179+
# List workspaces in text format (names only)
180+
$ fab ls
181+
workspace1
182+
workspace2
183+
184+
# Same command with JSON output
185+
$ fab ls --output_format json
186+
{
187+
"timestamp": "2026-01-06T08:00:00.000Z",
188+
"status": "Success",
189+
"command": "ls",
190+
"result": {
191+
"data": [
192+
{
193+
"name": "workspace1"
194+
},
195+
{
196+
"name": "workspace2"
197+
}
198+
]
199+
}
200+
}
201+
```
202+
203+
### Configuration Examples
204+
```bash
205+
# Check current output format
206+
$ fab config get output_format
207+
text
208+
209+
# Change to JSON as default
210+
$ fab config set output_format json
211+
* Configuration 'output_format' set to 'json'
212+
213+
# All subsequent commands use JSON
214+
$ fab auth status
215+
{
216+
"timestamp": "2026-01-06T08:00:00.000Z",
217+
"status": "Success",
218+
"command": "auth",
219+
"result": {
220+
"data": [
221+
{
222+
"logged_in": "true",
223+
"account": "user@example.com",
224+
"tenant_id": "12345678-1234-1234-1234-123456789012"
225+
}
226+
]
227+
}
228+
}
229+
230+
# Override for single command
231+
$ fab auth status --output_format text
232+
Logged In: true
233+
Account: user@example.com
234+
Tenant ID: 12345678-1234-1234-1234-123456789012
235+
```
236+
237+
### Automation and Scripting Examples
238+
239+
#### Redirecting Output
240+
```bash
241+
# Save results to file while seeing progress
242+
$ fab ls --output_format json > workspaces.json
243+
Processing workspace list...
244+
245+
# Save only errors for logging
246+
$ fab command 2> error.log
247+
```
248+
249+
## Best Practices
250+
251+
### Interactive Use
252+
- Keep the default `text` format for better readability
253+
- Use `-l` flag with text format to see detailed information in tables
254+
- Progress and status messages will appear regardless of output format
255+
256+
### Automation and Scripting
257+
- Set `output_format json` in config for scripts and automation
258+
- Use `--output_format json` for specific commands that need machine parsing
259+
- Always check the `status` field in JSON responses for error handling
260+
261+
### Command-Specific Tips
262+
- Use `--output_format text` override when you need human-readable output from a JSON-configured CLI
263+
- Combine with other flags like `--all` to include hidden data in JSON output
264+
- Use shell redirection to separate data output from informational messages
265+
266+
## Related Documentation
267+
268+
- [Configuration Management](settings.md) - Managing CLI settings and preferences
269+
- [Parameters](parameters.md) - Global flags and command parameters
270+
- [Exit Codes](exit_codes.md) - Understanding command exit codes
271+
- [Configuration Examples](../examples/config_examples.md) - Practical configuration examples

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ nav:
6464
- Resource Types: essentials/resource_types.md
6565
- CLI Parameters: essentials/parameters.md
6666
- CLI Input: essentials/input.md
67+
- Output Format: essentials/output_format.md
6768
- Modes: essentials/modes.md
6869
- Settings: essentials/settings.md
6970
- Environment Variables: essentials/env_vars.md

0 commit comments

Comments
 (0)