texio-cli 0.1.1

Reliable Markdown operations for shell scripts and AI agents
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

# CLI contract

This document defines the stable Texio 0.x command-line contract. Changes that
break documented syntax, output schemas, or exit-code meanings require a minor
version release and release-note migration guidance.

## Input and output

`FILE` accepts a UTF-8 Markdown path. Use `-` to read the document from stdin
for `headings`, `section`, and non-writing `replace` operations. `--from -`
reads replacement content from stdin; a command cannot use stdin for both the
document and its replacement.

Normal results go to stdout. Diagnostics go to stderr. Commands never prompt.

```text
texio headings FILE [--json]
texio section FILE HEADING [--body-only] [--json]
texio replace FILE --section HEADING (--from FILE | --text TEXT)
                    (--write | --dry-run | --stdout)
```

Replacement always requires one explicit mode:

- `--write` atomically updates a filesystem path.
- `--dry-run` prints a unified diff and changes nothing.
- `--stdout` prints the complete updated document and changes nothing.

`--write` is rejected when the document is read from stdin.

## JSON

`headings --json` returns an array of objects with `level` and `title`.
`section --json` returns an object with `heading`, `level`, and `content`.
Output is one compact JSON value followed by a newline.

Pass `--error-format json` anywhere in a command to emit runtime failures as one
JSON object on stderr:

```json
{"error":{"code":"section_not_found","message":"section not found: Missing"}}
```

The error object and its string `code` are stable. Runtime codes are `usage`,
`input`, `section_not_found`, `ambiguous_section`, and `write`. Command-line
syntax errors are generated by the argument parser and remain human-readable.

## Exit codes

| Code | Meaning |
| ---: | --- |
| 0 | Success |
| 2 | Invalid command line or unsafe input/output combination |
| 3 | Input could not be read as UTF-8 Markdown |
| 4 | Requested section was not found |
| 5 | Section name was ambiguous |
| 6 | Atomic write failed |

Successful `--dry-run` exits with 0 even when the preview contains changes.