> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Output Modes

> How to control the output format of the Nexudus CLI for human use, scripting, and AI assistant integration.

# Output Modes

Every CLI command supports four output modes, selected via global flags. The default mode produces human-friendly terminal tables.

## Available modes

| Flag      | Mode         | Best for                                              |
| --------- | ------------ | ----------------------------------------------------- |
| *(none)*  | **Table**    | Interactive terminal use — rich, formatted tables     |
| `--json`  | **JSON**     | Scripting and automation — raw JSON envelope          |
| `--md`    | **Markdown** | Documentation and reports — Markdown-formatted tables |
| `--agent` | **Agent**    | AI assistants — JSON envelope with enhanced summary   |

## The output envelope

When using `--json` or `--agent`, every command returns a standardised JSON envelope:

```json theme={null}
{
  "ok": true,
  "data": [ ... ],
  "summary": "Found 3 businesses (page 1/1)",
  "breadcrumbs": ["businesses", "list"],
  "meta": {
    "total": 3,
    "page": 1,
    "pageSize": 25,
    "totalPages": 1
  }
}
```

| Field         | Description                                                                                                             |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `ok`          | `true` on success, `false` on failure                                                                                   |
| `data`        | The response payload — an array for list operations, an object for single-entity operations, or `null` on some failures |
| `summary`     | A human-readable description of the result                                                                              |
| `breadcrumbs` | The command path that produced the output (e.g., `["products", "create"]`)                                              |
| `meta`        | Pagination metadata (present only on list commands)                                                                     |

### Error envelope

When a command fails, the envelope looks like:

```json theme={null}
{
  "ok": false,
  "data": null,
  "summary": "Not logged in. Run 'nexudus login' first.",
  "breadcrumbs": ["businesses", "list"]
}
```

Always check `ok` first before processing `data`.

## Examples

### Table mode (default)

```bash theme={null}
nexudus businesses list
```

Produces a formatted table in your terminal using rich formatting (colours, borders, alignment).

### JSON mode

```bash theme={null}
nexudus businesses list --json
```

Returns the raw JSON envelope — ideal for piping into `jq`, processing in scripts, or integrating with other tools:

```bash theme={null}
nexudus products list --json | jq '.data[] | .Name'
```

### Markdown mode

```bash theme={null}
nexudus businesses list --md
```

Produces Markdown-formatted tables suitable for pasting into documentation, tickets, or chat messages.

### Agent mode

```bash theme={null}
nexudus businesses list --agent
```

Returns the JSON envelope with an enhanced `summary` field optimised for AI assistant consumption. This is the mode that [Agent Skills](/cli/agent-skills-overview) use to communicate with the CLI.