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

# Output formats

> Pretty tables, JSON, quiet, and TOON - and when to use each.

Every command can return one of four output formats. In an interactive terminal, pretty output is the default. Use the flags below for machine-readable output.

| Format | Flag                      | Best for                                                          |
| ------ | ------------------------- | ----------------------------------------------------------------- |
| Pretty | *(default in a terminal)* | Reading a result yourself.                                        |
| JSON   | `--json`                  | Machine-readable payloads with pagination metadata.               |
| Quiet  | `--quiet`                 | Piping an identifier into another command or `jq`.                |
| TOON   | `--toon`                  | Feeding list/show output back to an LLM (fewer tokens than JSON). |

If more than one is set, precedence is `--toon` > `--quiet` > `--json` > pretty.

## Pretty

The default in a terminal: tables for lists and key-value pairs for a single record. It is intended for people, not scripts.

```bash theme={"system"}
neetokb articles list --state published
```

## JSON

JSON wraps the resource body with breadcrumbs and, for list commands, pagination details:

```json theme={"system"}
{
  "data": [
    {
      "id": "a1b2c3d4-1111-2222-3333-444455556666",
      "slug": "getting-started",
      "title": "Getting Started Guide",
      "state": "published"
    }
  ],
  "breadcrumbs": [{ "label": "Show", "command": "neetokb articles show <id>" }],
  "pagination": {
    "total_records": 250,
    "total_pages": 10,
    "current_page_number": 1,
    "page_size": 30
  }
}
```

For list commands, `data` is the array of records; the CLI removes the API response's resource key. For `show`, `data` holds the API response body, such as `{ "article": { ... } }`.

`breadcrumbs` is omitted when empty, and `pagination` appears only on list commands. The CLI automatically uses JSON when output is piped (a non-TTY); use `--json` to force it.

## Quiet

`--quiet` returns only the `data` payload. For `create` and `update`, it prints the resource identifier; for `delete`, it prints `success`. This is useful in scripts:

```bash theme={"system"}
neetokb articles create \
  --title "Getting Started" --category "Getting Started" \
  --html-content "<h1>Welcome</h1>" --state draft \
  --quiet
# → prints the new article id
```

## TOON

`--toon` encodes the same data as TOON (Token-Optimized Output Notation). It keeps the JSON shape while compressing whitespace and keys, typically using 30–60% fewer tokens. Use it when giving list or show output to an AI assistant.

```bash theme={"system"}
neetokb search --search-term "billing" --toon
```

## Pagination

List commands return results in pages. The flags below control paging, and the JSON envelope's `pagination` block shows your position in the result set.

### Pagination Parameters

<ParamField body="--page" type="integer">
  The page of results to retrieve, starting from 1.
</ParamField>

<ParamField body="--page-size" type="integer">
  The number of records to return per page (max 100).
</ParamField>

### Example Usage

```bash theme={"system"}
neetokb articles list --page 2 --page-size 50
```

This returns the second page of articles, with 50 records per page.

### Response Structure

For list commands the JSON envelope carries a `pagination` block alongside the data:

```json theme={"system"}
{
  "pagination": {
    "total_records": 250,
    "total_pages": 5,
    "current_page_number": 2,
    "page_size": 50
  }
}
```

<ResponseField name="pagination.total_records" type="integer">
  The total number of records across all pages.
</ResponseField>

<ResponseField name="pagination.total_pages" type="integer">
  The total number of pages available.
</ResponseField>

<ResponseField name="pagination.current_page_number" type="integer">
  The page you are currently on.
</ResponseField>

<ResponseField name="pagination.page_size" type="integer">
  The number of records returned per page.
</ResponseField>

### Default Behavior

If you omit both flags, the CLI lets the server use its defaults. Either flag overrides the defaults; `--page-size` accepts up to 100.

### Best Practices

* To retrieve every page, increment `--page` until `current_page_number == total_pages`.
* Use `--json` or `--toon` in scripts when you need the `pagination` block. `--quiet` removes the envelope, so it does not include pagination metadata.
* Check `total_records` before you begin to estimate the work involved.