#tplvane --json, version 1

Every tplvane 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. Notes and warnings, which normally go to stderr, are not printed; warnings are in the document. 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 file name) are written as \x1b, so that a file cannot send commands to the terminal.

The schemas are JSON Schema (draft 2020-12) files in cli-json/. The tests of tplvane check the output of every command, and of every kind of error, against them. They use only this subset of JSON Schema: type, properties, required, additionalProperties, items, enum, const, oneOf, anyOf, minimum, pattern, and $ref to $defs.

The field tplvane 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:

{ "tplvane": 1, "command": "inspect", "ok": true, "result": { } }

On failure:

{
  "tplvane": 1,
  "command": "render",
  "ok": false,
  "error": {
    "name": "TvError",
    "code": "TV_E_FILE_EXISTS",
    "message": "The file \"offer-filled.docx\" already exists.",
    "location": {},
    "hint": "Add --force to replace it, or name another file with --output.",
    "docsUrl": "https://github.com/DevXord/tplvane/blob/main/docs/errors.md#tv_e_file_exists",
    "details": { "path": "offer-filled.docx" },
    "errors": []
  },
  "try": "tplvane render offer.docx data.json --force"
}

• error: the same data as TvError.toJSON() in the library. The codes are described in the error catalogue of tplvane (docs/errors.md in the repository). A template with problems gives TV_E_TEMPLATE_INVALID and data with problems TV_E_DATA_INVALID, each with every problem in errors, with its place in the template and, for data, the path of the field (details.dataPath, details.pointer).
• try: a ready-to-run command that fixes the error when there is an obvious one (the closest command or option, --force, --fetch-images), 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: packages/tplvane/docs/cli-json.md (version 1.0.0)