#xlvane --json, version 1

Every xlvane command accepts --json. The command then prints exactly one JSON document to stdout, without colour, followed by a line feed. When stdout is not a terminal (a pipe, a file, a program reading the output) the document is on one line; on a terminal it is indented with two spaces. The data is the same either way. Progress lines and notes, which normally go to stderr, are not printed. The exit codes are the same as without --json. --help and --version always print text.

Text in the JSON output is never changed. In the text output for people, control characters from files or arguments (for example the escape character in a cell) are written as \x1b, so that a file cannot send commands to the terminal (docs/decisions.md D-R02).

Dates are ISO 8601 text without a time zone, as in CSV: 2024-01-31 at midnight, otherwise 2024-01-31T13:45:00 (with .sss when there are milliseconds). Sheet dates have no time zone. Document properties (created, modified in inspect) are instants and keep the Z.

The schemas are JSON Schema (draft 2020-12) files in docs/cli-json/. tests/cli/json.test.ts checks the output of every command against them. They use only this subset of JSON Schema:

• type, properties, required, additionalProperties, items;
• enum, const, oneOf, anyOf, minimum, pattern;
• $ref to $defs.

The field xlvane changes only when a field is removed or changes meaning; new fields may be added within a version, so programs should ignore fields they do not know. The schemas list every field of the current release and forbid others, so that the tests notice an undocumented field.

#Envelope

On success:

{ "xlvane": 1, "command": "read", "ok": true, "result": { } }

On failure:

{
  "xlvane": 1,
  "command": "read",
  "ok": false,
  "error": {
    "name": "XlvError",
    "code": "XLV_E_SHEET_NOT_FOUND",
    "message": "The workbook has no sheet named \"Salse\".",
    "location": { "sheet": "Salse" },
    "hint": "Did you mean \"Sales\"? Available sheets: \"Sales\", \"Costs\". Sheet names are case-sensitive.",
    "docsUrl": "https://github.com/DevXord/xlvane/blob/main/docs/errors.md#xlv_e_sheet_not_found",
    "details": { "available": ["Sales", "Costs"], "path": "report.xlsx" }
  },
  "try": "xlvane read report.xlsx --sheet Sales --json"
}

Field notes:

• error: the same data as XlvError.toJSON() in the library. Codes are listed in errors.md. When the error comes from a file, details.path names it.
• try: a ready-to-run command that fixes the error when there is an obvious one (for example the closest sheet name, or --force), otherwise null. It is quoted for POSIX shells.
• command: null when the command itself is unknown.

The error envelope is defined in cli-json/common.schema.json ($defs/errorEnvelope).

#Exit codes

#Commands

Source: docs/cli-json.md (version 1.2.2)