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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
# CLI Reference
## Installation
```bash
go install github.com/grindlemire/go-tui/cmd/tui@latest
```
This installs the `tui` binary, which compiles `.gsx` files to Go, formats them, validates syntax, and runs the language server for editor integration.
## Commands
### tui generate
```bash
tui generate [options] [path...]
```
Compiles `.gsx` files into Go source files. Each `input.gsx` produces a corresponding `input_gsx.go` in the same directory. Hyphens in filenames are converted to underscores (e.g., `my-app.gsx` becomes `my_app_gsx.go`).
Never hand-edit the generated `_gsx.go` files. They get overwritten on the next run.
**Options:**
| Flag | Description |
|------|-------------|
| `-v` | Verbose output (lists files found and processed) |
**Path formats:**
| Pattern | Behavior |
|---------|----------|
| `./...` | Recursively find all `.gsx` files |
| `./components` | Process `.gsx` files in that directory (non-recursive) |
| `header.gsx` | Process a single file |
| *(none)* | Defaults to current directory (`.`) |
```bash
tui generate ./... # all .gsx files recursively
tui generate ./components # one directory
tui generate header.gsx # one file
tui generate -v ./... # verbose
```
The command exits with code 1 if any file has errors. Error messages include the filename, line, and column.
### tui check
```bash
tui check [options] [path...]
```
Parses and analyzes `.gsx` files without generating any output. Validates syntax, element names, attribute types, and imports. Same path formats as `generate`.
**Options:**
| Flag | Description |
|------|-------------|
| `-v` | Verbose output |
```bash
tui check ./... # check all files
tui check header.gsx # check one file
```
Exits with code 0 if all files pass. Exits with code 1 and prints errors to stderr if any file has problems.
### tui fmt
```bash
tui fmt [options] [path...]
```
Formats `.gsx` files. By default, modifies files in place. Runs files in parallel for speed.
**Options:**
| Flag | Description |
|------|-------------|
| `--check` | Check if files are formatted without modifying them. Exits with code 1 if any file needs formatting. |
| `--stdout` | Print formatted output to stdout instead of writing back to disk. When processing multiple files, each is prefixed with `// filename`. |
```bash
tui fmt ./... # format all files in place
tui fmt --check ./... # CI check: fail if any file isn't formatted
tui fmt --stdout file.gsx # preview formatted output
```
### tui lsp
```bash
tui lsp [options]
```
Starts the go-tui language server, communicating over stdin/stdout using the Language Server Protocol (JSON-RPC). Editors connect to this process for features like:
- Syntax error diagnostics
- Autocompletion for elements, attributes, and Tailwind classes
- Hover documentation
- Go-to-definition
- Find references
- Semantic token highlighting
- Document formatting
**Options:**
| Flag | Description |
|------|-------------|
| `--log FILE` | Write debug logs to the given file. Useful for troubleshooting LSP issues. |
```bash
tui lsp # start on stdio
tui lsp --log /tmp/tui-lsp.log # start with debug logging
```
### tui version
```bash
tui version
```
Prints the version string, e.g., `tui version 0.1.0`.
### tui help
```bash
tui help
```
Prints the full usage message with all commands and examples. Also triggered by `-h` or `--help`.
## Editor Integration
The `tui lsp` command provides a Language Server Protocol server. Here's how to set it up in common editors.
### VS Code
Install the official go-tui extension, which bundles the LSP client, syntax highlighting, and file associations:
- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=grindlemire.go-tui)
- [Open VSX](https://open-vsx.org/extension/grindlemire/go-tui) (for VS Code forks like Cursor)
The extension automatically runs `tui lsp` for `.gsx` files. No manual configuration needed.
The extension also registers a file nesting pattern so each generated `*_gsx.go` file collapses under its `.gsx` source in the Explorer. VS Code's file nesting is off by default, so enable it once to use it:
```json
{
"explorer.fileNesting.enabled": true
}
```
Put that in a project's `.vscode/settings.json` to scope nesting to that project rather than every repository you open.
### Neovim
With [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig), add a custom server configuration:
```lua
local lspconfig = require('lspconfig')
local configs = require('lspconfig.configs')
if not configs.tui then
configs.tui = {
default_config = {
cmd = { 'tui', 'lsp' },
filetypes = { 'gsx' },
root_dir = lspconfig.util.root_pattern('go.mod'),
},
}
end
lspconfig.tui.setup({})
```
You'll also want to associate `.gsx` files with a filetype:
```lua
vim.filetype.add({
extension = {
gsx = 'gsx',
},
})
```
### Debugging the LSP
If the language server isn't working as expected, start it with logging enabled:
```bash
tui lsp --log /tmp/tui-lsp.log
```
Then tail the log file while editing to see requests, responses, and errors:
```bash
tail -f /tmp/tui-lsp.log
```
## Cross-References
- [GSX Syntax Reference](gsx-syntax.md) — the file format that `tui generate` compiles
- [Getting Started Guide](../guides/01-getting-started.md) — project setup walkthrough using the CLI
|