CLI Reference

Installation

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

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:

Path formats:

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

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:

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

tui fmt [options] [path...]

Formats .gsx files. By default, modifies files in place. Runs files in parallel for speed.

Options:

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

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:

tui lsp                         # start on stdio
tui lsp --log /tmp/tui-lsp.log  # start with debug logging

tui version

tui version

Prints the version string, e.g., tui version 0.1.0.

tui help

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
• Open VSX (for VS Code forks like Cursor)

The extension automatically runs tui lsp for .gsx files. No manual configuration needed.

Neovim

With nvim-lspconfig, add a custom server configuration:

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:

vim.filetype.add({
    extension = {
        gsx = 'gsx',
    },
})

Debugging the LSP

If the language server isn't working as expected, start it with logging enabled:

tui lsp --log /tmp/tui-lsp.log

Then tail the log file while editing to see requests, responses, and errors:

tail -f /tmp/tui-lsp.log

Cross-References

• GSX Syntax Reference — the file format that tui generate compiles
• Getting Started Guide — project setup walkthrough using the CLI