diff --git a/docs/essentials/output_format.md b/docs/essentials/output_format.md new file mode 100644 index 000000000..6ef3a1a6b --- /dev/null +++ b/docs/essentials/output_format.md @@ -0,0 +1,271 @@ +# Output Format - User Guide + +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. + +## Overview + +The output format feature allows you to control how command results are displayed. The CLI supports two primary output formats: +- **Text Format** (default): Human-readable, formatted output optimized for terminal viewing +- **JSON Format**: Structured, machine-parseable output suitable for scripting and automation + +## Supported Output Formats + +### Text Format (`text`) +The default format that provides human-readable output with: +- Clean, formatted display +- Headers for tabular data when using `-l` or `-q` flags +- Color-coded status indicators +- Progress indicators and informational messages +- Unix-style listings for directory-like commands + +### JSON Format (`json`) +Structured output format that provides: +- Consistent JSON schema across all commands +- Machine-parseable results +- Standardized error reporting +- Timestamp and command metadata + +## Configuration + +### Command-Line Flag +Override the output format for any command using the global `--output_format` flag: + +```bash +# Use JSON format for a single command +fab ls --output_format json + +# Use text format explicitly +fab auth status --output_format text +``` + +**Available Values:** +- `json` - JSON structured output +- `text` - Human-readable text output (default) + +### Configuration File +Set the default output format using the [`fab config set`](../examples/config_examples.md) command: + +```bash +# Set JSON as default format +fab config set output_format json + +# Set text as default format (default) +fab config set output_format text + +# View current setting +fab config get output_format +``` + +The configuration is stored in your Fabric CLI configuration file and applies to all subsequent commands unless overridden by the `--output_format` flag. + +## JSON Output Schema + +### Success Response Structure +```json +{ + "timestamp": "2026-01-06T08:00:00.000Z", + "status": "Success", + "command": "command_name", + "result": { + "data": [ + { + "id": "example-id", + "name": "example-name", + "type": "example-type" + } + ], + "hidden_data": [ + ".capacities", + ".gateways" + ], + "message": "Operation completed successfully" + } +} +``` + +### Error Response Structure +```json +{ + "timestamp": "2026-01-06T08:00:00.000Z", + "status": "Failure", + "command": "command_name", + "result": { + "message": "Unable to find workspace: workspace1", + "error_code": "ERROR_WORKSPACE_NOT_FOUND" + } +} +``` + +### JSON Schema Fields + +#### Root Level +- **`timestamp`** (string): ISO 8601 UTC timestamp when the command completed +- **`status`** (string): Either `"Success"` or `"Failure"` +- **`command`** (string, optional): The primary command that was executed +- **`result`** (object): Contains the actual command results + +#### Result Object +- **`data`** (array, optional): Primary output data when available +- **`hidden_data`** (array, optional): Virtual workspace items like capacities, gateways, managed private endpoints etc... +- **`message`** (string, optional): Success message or operation description +- **`error_code`** (string, optional): Standardized error code (only present on failures) + +## Text Output Behavior + +### Success Output +Text format provides context-aware formatting: + +```bash +# Basic directory listing (names only) +$ fab ls +workspace1 +workspace2 + +# Directory listing with details (-l flag) +$ fab ls -l +name id capacityName capacityId capacityRegion +--------------------------------------------------------------------------------------------------------------------- +workspace1 12345678-1234-1234-1234-123456789012 MyCapacity 87654321-4321-4321-4321-210987654321 East US +workspace2 12345678-1234-1234-1234-123456789013 MyCapacity 87654321-4321-4321-4321-210987654321 East US + +# Simple success message +$ fab auth logout +* Logged out of Fabric account + +# Data with message (mkdir shows table by default) +$ fab mkdir workspace1 +* 'workspace1' created +``` + +### Error Output +Error messages include the error code in brackets followed by the message: + +```bash +$ fab ls invalid-workspace +x ls: [NotFound] The Workspace 'invalid-workspace.Workspace' could not be found +``` + +### Informational Output +Informational messages (warnings, progress, debug info) are always sent to `stderr` regardless of output format: + +```bash +$ fab mv ws1.Workspace/r1.Report ws1.Workspace/ +Moving '/ws.Workspace/r1.Report' → '/ws1.Workspace/r1.Report'... +* Move completed +``` + +## Stream Behavior + +### Standard Output (stdout) +- **All command results** (both success and error responses) +- **JSON format**: All JSON responses +- **Text format**: Command results, data, and final status messages + +### Standard Error (stderr) +- Warning messages +- Informational messages +- Debug messages +- Progress indicators + +This separation allows you to: +- Redirect command results to files while preserving interactive feedback +- Filter informational messages separately from actual data +- Pipe JSON output to processing tools without interference + +## Usage Examples + +### Basic Usage +```bash +# List workspaces in text format (names only) +$ fab ls +workspace1 +workspace2 + +# Same command with JSON output +$ fab ls --output_format json +{ + "timestamp": "2026-01-06T08:00:00.000Z", + "status": "Success", + "command": "ls", + "result": { + "data": [ + { + "name": "workspace1" + }, + { + "name": "workspace2" + } + ] + } +} +``` + +### Configuration Examples +```bash +# Check current output format +$ fab config get output_format +text + +# Change to JSON as default +$ fab config set output_format json +* Configuration 'output_format' set to 'json' + +# All subsequent commands use JSON +$ fab auth status +{ + "timestamp": "2026-01-06T08:00:00.000Z", + "status": "Success", + "command": "auth", + "result": { + "data": [ + { + "logged_in": "true", + "account": "user@example.com", + "tenant_id": "12345678-1234-1234-1234-123456789012" + } + ] + } +} + +# Override for single command +$ fab auth status --output_format text +Logged In: true +Account: user@example.com +Tenant ID: 12345678-1234-1234-1234-123456789012 +``` + +### Automation and Scripting Examples + +#### Redirecting Output +```bash +# Save results to file while seeing progress +$ fab ls --output_format json > workspaces.json +Processing workspace list... + +# Save only errors for logging +$ fab command 2> error.log +``` + +## Best Practices + +### Interactive Use +- Keep the default `text` format for better readability +- Use `-l` flag with text format to see detailed information in tables +- Progress and status messages will appear regardless of output format + +### Automation and Scripting +- Set `output_format json` in config for scripts and automation +- Use `--output_format json` for specific commands that need machine parsing +- Always check the `status` field in JSON responses for error handling + +### Command-Specific Tips +- Use `--output_format text` override when you need human-readable output from a JSON-configured CLI +- Combine with other flags like `--all` to include hidden data in JSON output +- Use shell redirection to separate data output from informational messages + +## Related Documentation + +- [Configuration Management](settings.md) - Managing CLI settings and preferences +- [Parameters](parameters.md) - Global flags and command parameters +- [Exit Codes](exit_codes.md) - Understanding command exit codes +- [Configuration Examples](../examples/config_examples.md) - Practical configuration examples \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 06390b353..1dd382196 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -64,6 +64,7 @@ nav: - Resource Types: essentials/resource_types.md - CLI Parameters: essentials/parameters.md - CLI Input: essentials/input.md + - Output Format: essentials/output_format.md - Modes: essentials/modes.md - Settings: essentials/settings.md - Environment Variables: essentials/env_vars.md