rototo 0.1.0-alpha.3

Control plane for runtime configuration of your application.
Documentation 
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
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

# JSON Output Reference

`--json` is the format automation should use for the rototo CLI. Human output
may change to read better. CI, agents, and tests should consume JSON output.

The rule I use for automation is straightforward: do not parse human output.
Ask for JSON, assert the fields you depend on, and let human output stay
readable for operators.

## Common Rules

JSON output is pretty-printed.

Diagnostics use the shape described in `reference-diagnostics`.

When a command reports workspace documents, each document summary uses this
shape:

```json
{
  "id": 0,
  "path": "variables/account-limits.toml",
  "uri": "file:///workspace/variables/account-limits.toml",
  "version": null,
  "kind": "variable"
}
```

`version` is reserved for editor and overlay integrations. Disk-backed CLI
documents usually report `null`.

## `lint --json`

```json
{
  "workspace": "/workspace",
  "documents": [],
  "diagnostics": []
}
```

Use this in CI when you need structured diagnostics tied to files, ranges, and
stable rule ids.

## `show --json`

`show` returns selected config and catalog views. Use it when automation needs
to read configured workspace data or the diagnostic catalog:

```json
{
  "command": "show",
  "workspace": "/workspace",
  "schemas": [],
  "resources": [],
  "variables": [],
  "qualifiers": [],
  "lint_rules": [],
  "lint_authorities": [],
  "linters": []
}
```

Selected variables, qualifiers, and resources include `id`, `uri`, `path`, and
their TOML content converted to JSON.

Resource output includes an `objects` table when resource object files exist.

## `inspect --json`

`inspect` returns the most complete workspace explanation. Use it when tooling
needs dependencies, consumers, runtime status, and optional resolution traces:

```json
{
  "workspace": "/workspace",
  "documents": [],
  "runtime": { "status": "available" },
  "diagnostics": [],
  "schemas": [],
  "resources": [],
  "variables": [],
  "qualifiers": [],
  "lint_rules": [],
  "lint_authorities": [],
  "linters": []
}
```

Selected variables, resources, qualifiers, and schemas include dependencies,
consumers, and diagnostics. When `--context` is supplied, selected variables
and qualifiers can include `trace`.

`runtime.status` is `available` when the workspace compiles into a runtime
model. Otherwise it is `unavailable` with a reason.

## `resolve --json`

```json
{
  "workspace": "/workspace",
  "variables": [],
  "qualifiers": []
}
```

Use `resolve --json` when automation needs to know what value or qualifier
result rototo selected. See `reference-resolution-output` for the trace fields.

## `docs --json`

`rototo docs --json` lists navigation sections. This is mainly for docs
publishers and tools that need to mirror the bundled docs order:

```json
{
  "sections": [
    {
      "title": "Reference",
      "pages": [
        { "id": "reference-workspace-layout", "title": "Workspace Layout" }
      ]
    }
  ]
}
```

`rototo docs -p <page> --json` returns page metadata and Markdown. `docs -s`
returns search hits with page ids, line numbers, and match spans.

## `fixtures --json`

`fixtures --json` reports the fixture generation result. Use it when CI or
scaffolding tools need to know which fixture files were written. The generated
files are TOML fixtures under the directory passed with `--out`.

## Error Output

Command-line parse errors and runtime errors are printed to stderr and return a
non-zero exit code. They are not wrapped in the command's JSON success shape.

When automation needs structured lint failures, prefer `rototo lint --json`
over parsing stderr from a failed command.