How to Use the OfficeCLI --json Flag for Machine-Parseable Output Across All Commands

The OfficeCLI --json global flag forces every command to return structured JSON instead of human-readable tables, enabling seamless integration with automation tools like jq, Python, and CI/CD pipelines.

OfficeCLI is built on yargs, which supports global options that propagate automatically to every sub-command. The --json flag is registered as a boolean option in the entry point before any command modules load, ensuring consistent machine-parseable output across the entire CLI surface.

Global Option Architecture

The --json flag is not command-specific; it is defined as a global option that injects into every command handler's argument vector.

Registration in src/cli.ts

In [src/cli.ts](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/cli.ts), the CLI declares the global option using yargs' .option() method:

yargs
  .option('json', {
    type: 'boolean',
    describe: 'Print output as JSON (machine‑parseable)'
  })

Because this registration occurs before command modules are loaded, yargs automatically appends the json property to the argv object passed to every handler.

Propagation to Command Handlers

Each command module in src/commands/ receives the parsed arguments through its handler function. The flag is typically destructured from the argv object:

export const handler = async (argv: Arguments) => {
  const { json } = argv;
  // Command logic executes here...
};

This pattern is consistent across [src/commands/list.ts](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/commands/list.ts), [src/commands/create.ts](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/commands/create.ts), and [src/commands/delete.ts](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/commands/delete.ts).

Conditional Formatting Logic

After executing command logic, handlers build a plain-object result (e.g., { status: 'success', data: ... }). The output path branches based on the json flag:

if (json) {
  // Machine-parseable path
  console.log(JSON.stringify(result, null, 2));
} else {
  // Human-friendly path with tables and colors
  renderHumanReadable(result);
}

The concrete formatting implementation typically lives in [src/utils/formatter.ts](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/utils/formatter.ts), though the conditional check appears in individual command files.

Practical Usage Examples

Append --json to any OfficeCLI command to receive a consistent JSON envelope instead of formatted text.

Listing Resources

# List all document spaces as JSON

office list spaces --json

Creating Resources

# Create a Word document and receive parseable output

office create doc my-presentation.docx --json

Deleting Resources

# Delete a user and get status confirmation in JSON

office delete user alice@example.com --json

All commands return a uniform envelope structure:

{
  "status": "success",
  "data": {
    "id": "5f8c9e7b-3a2a-4e1d-9c8b-1d2e3f4a5b6c",
    "name": "my-presentation.docx",
    "createdAt": "2024-10-01T12:34:56.000Z"
  }
}

Parsing Output in Automation Scripts

The JSON output is designed for piping into standard Unix utilities and scripting languages.

Extracting Values with jq

# Grab only the newly created document's ID

office create doc new.docx --json | jq -r '.data.id'

Embedding in Bash Scripts

#!/usr/bin/env bash
docInfo=$(office list docs --json | jq '.data[] | select(.name=="report.docx")')
echo "Document ID: $(echo "$docInfo" | jq -r .id)"

SDK Integration

The Node SDK wrapper recognizes the same JSON envelope format. According to the type definitions in [sdk/node/index.d.ts](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.d.ts#L21), the SDK returns "the JSON envelope (object/array) for --json commands, or raw" output. This ensures behavioral parity whether invoking the CLI directly or programmatically through the SDK.

Summary

• Global availability: The --json flag is registered in src/cli.ts as a yargs global option, making it accessible to every command without individual registration.
• Consistent envelope: All commands return a standard JSON structure with status and data properties when the flag is present.
• Implementation pattern: Commands check argv.json and route output through JSON.stringify() in src/utils/formatter.ts or inline handlers.
• Automation ready: Output pipes directly into jq, Python's json module, or CI/CD systems for reliable programmatic parsing.

Frequently Asked Questions

Is the --json flag available for every OfficeCLI command?

Yes. Because the flag is defined as a global option in src/cli.ts before yargs loads command modules, it automatically appears in the argument vector of every handler, including list, create, delete, and any future commands.

What is the structure of the JSON output envelope?

OfficeCLI returns a consistent envelope containing a status field (typically "success" or "error") and a data field containing the command-specific payload. This structure is defined in the SDK types at sdk/node/index.d.ts and implemented across all command handlers.

How do I parse OfficeCLI JSON output in shell scripts?

Pipe the output to jq for filtering and extraction. For example, office list spaces --json | jq -r '.data[].id' extracts all space IDs. The --json flag ensures valid JSON even for error states, preventing parsing failures in downstream tools.

Does the Node SDK support machine-parseable output?

Yes. When using the Node SDK wrapper, the same JSON envelope format applies. The SDK type definitions explicitly reference the JSON envelope structure for programmatic access, maintaining parity with direct CLI invocation using --json.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}