Output formats - NeetoKB Docs

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.

neetokb articles list --state published

JSON

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

{
  "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:

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.

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

integer

The page of results to retrieve, starting from 1.

integer

The number of records to return per page (max 100).

Example Usage

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:

{
  "pagination": {
    "total_records": 250,
    "total_pages": 5,
    "current_page_number": 2,
    "page_size": 50
  }
}

integer

The total number of records across all pages.

integer

The total number of pages available.

integer

The page you are currently on.

integer

The number of records returned per page.

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.

​Pretty

​JSON

​Quiet

​TOON

​Pagination

​Pagination Parameters

​Example Usage

​Response Structure

​Default Behavior

​Best Practices

Pretty

JSON

Quiet

TOON

Pagination

Pagination Parameters

Example Usage

Response Structure

Default Behavior

Best Practices