Output formats - NeetoInvoice Docs

Four output modes are available on every command. They are selected with the global flags --json, --quiet, and --toon. Precedence when more than one is set: --toon > --quiet > --json > pretty.

Global flags

Every command accepts these flags. They are left out of the per-command flag tables in the command reference.

Flag	Description
`--json`	Output as JSON. Forces the envelope even on a terminal.
`--quiet`	Output raw data only, with no envelope.
`--toon`	Output in TOON format, token-optimized for AI agents.
`--subdomain <name>`	Override the saved subdomain. Required when several workspaces are signed in; see Authentication.

Pretty

The default when standard output is a terminal. Arrays render as aligned tables, objects as key-value pairs, and related commands are appended as breadcrumbs.

neetoinvoice whoami

Authenticated as oliver@example.com on acme.neetoinvoice.com (default).

Column choice, column order, and truncation all adapt to the terminal width, so pretty output is meant for humans to read. Do not parse it. Use --json or --toon for anything that consumes the output programmatically.

JSON envelope

Used automatically when output is piped or redirected, and forced on a terminal with --json.

neetoinvoice projects list --client-id 7c1f5e2a9b --json

{
  "data": [
    {
      "id": "f627c399-379d-4d07-a6f6-90b7c9470ac0",
      "identifier": "89d1b47d9f36af3c9ecf",
      "name": "Website Redesign",
      "client_id": "3f0c0f87-ddc7-45f4-ad7a-c3690fa04963",
      "status": "active",
      "requires_daily_entry": false
    }
  ],
  "breadcrumbs": [
    { "label": "Show", "command": "neetoinvoice projects show <project-id>" }
  ],
  "pagination": {
    "total_records": 1,
    "total_pages": 1,
    "current_page_number": 1,
    "page_size": 30
  }
}

breadcrumbs is omitted when empty. pagination is present on every list command (clients list, projects list, time-entries list, and team-members list), though only time-entries list and team-members list accept --page and --page-size; see Pagination. Commands that print a message rather than a record, such as login, logout, whoami, and the recipients, project-users, and team-members delete commands, emit { "message": "..." } without a data key.

Quiet

--quiet drops the envelope and emits the payload alone. On action commands it prints just the identifier, which is what makes it useful in a pipeline.

CLIENT_ID=$(neetoinvoice clients create --name "Acme Corp" --quiet)
neetoinvoice recipients create \
  --client "$CLIENT_ID" \
  --name "Sam Smith" \
  --email sam@example.com \
  --user-email oliver@example.com

delete commands print success in quiet mode, except time-entries delete, which prints {"message":"Time entry deleted."}.

TOON

--toon emits Token-Optimized Output Notation: the same data as JSON with keys and whitespace compressed, typically 30 to 60 percent fewer tokens. Prefer it when piping list or show output into an AI assistant.

neetoinvoice time-entries list --client 7c1f5e2a9b --project 89d1b47d9f36af3c9ecf --toon

Parse it by reading keys the way you would with JSON.

Pagination

time-entries list, team-members list, clients list, and projects list all report their pages the same way: data holds the bare array of records, and a pagination object in the envelope carries total_records, total_pages, current_page_number, and page_size. Only time-entries list and team-members list accept --page (1-indexed) and --page-size (0 by default, which sends no page size and lets the API return 30 per page; maximum 100). clients list and projects list have no paging flags, so they always return the first page.

neetoinvoice time-entries list \
  --client 7c1f5e2a9b \
  --project 89d1b47d9f36af3c9ecf \
  --page 2 \
  --page-size 50

{
  "data": [
    { "id": "128c1dfc-b29f-4fda-9a05-8a90e197b81b", "hours": 2.5, "recorded_on": "2026-07-14" }
  ],
  "pagination": {
    "total_records": 92,
    "total_pages": 2,
    "current_page_number": 2,
    "page_size": 50
  }
}

To walk every page, increment --page until current_page_number equals total_pages. The --page flag on team-members list has no effect in this release; see team-members list.

Exit codes and errors

Every command exits non-zero on failure and writes the error to standard error, leaving standard output empty. Errors from the API are reported as API error (<status>): <message>, followed by any field errors and a suggestion for the common status codes. See Troubleshooting for the messages.

​Global flags

​Pretty

​JSON envelope

​Quiet

​TOON

​Pagination

​Exit codes and errors