XanoScript LSP CLI

A command-line interface for validating XanoScript (.xs) files using the XanoScript Language Server Protocol (LSP) server. Perfect for CI/CD pipelines, pre-commit hooks, and integration with AI CLI coding assistants like Claude Code, Codex, Gemini CLI, and more.

Latest release: v0.0.2 — see CHANGELOG.md for details.

Features

• ✅ Real-time Validation: Uses the official XanoScript LSP server for accurate diagnostics
• ✅ Auto-Discovery: Automatically finds and validates all .xs files in your project
• ✅ Multiple Output Formats: Human-readable or JSON output for easy parsing
• ✅ Claude Code Integration: Built-in slash command for AI-assisted error fixing
• ✅ Zero Configuration: Auto-detects the LSP server from your VS Code extension
• ✅ Fast: Validates files in parallel with real-time progress

Claude Code & Skill Setup (Start Here)

1. Install the CLI globally (or via npx) so xs-lint is on your PATH:

   npm install -g xanoscript-lint
   # or
   npx xanoscript-lint --help

2. In each XanoScript project directory, run:

   xs-setup --symlink

   This links the .claude skill and /xs-lint command to the installed CLI, enabling automatic validation and the Claude slash command.
3. Inside Claude Code, trigger manual validation with:

   /xs-lint

   You can pass file paths (e.g. /xs-lint functions/73_check_output_pii.xs), and the automatic skill will validate after every .xs edit.

Installation

Prerequisites

• Node.js 20 or higher
• XanoScript VS Code extension installed (xano.xanoscript) and opened at least once so the bundled language server is available locally

Install from npm

# Global install
npm install -g xanoscript-lint

# One-off run without installing
npx xanoscript-lint --help

Develop Locally

# Clone the repository
git clone https://github.com/welldundun/xano-lsp-cli.git
cd xano-lsp-cli

# Install dependencies
npm install

# Link globally (optional)
npm link

Usage

Basic Usage

# Validate all .xs files in current directory
xs-lint

Validate Specific Files

# Single file
xs-lint src/api/users.xs

# Multiple files
xs-lint src/api/users.xs src/api/posts.xs

# Pattern matching
xs-lint "src/api/**/*.xs"

Output Formats

# Human-readable output (default)
xs-lint

# JSON output (for parsing/integration)
xs-lint --json

# Quiet mode (suppress progress messages)
xs-lint --quiet

Pass File Lists via stdin (Automation-Friendly)

# Pipe newline-separated file paths for a stable command signature
printf "%s\n" src/api/users.xs src/api/posts.xs | xs-lint --json --stdin

This is ideal for Claude Skills or CI pipelines where you want to approve a single command and reuse it with different file sets.

CI Pipeline Example

changed_files="$(git diff --name-only origin/main...HEAD | rg '\\.xs$')" || true
if [ -n "$changed_files" ]; then
  printf "%s\n" "$changed_files" | xs-lint --json --stdin
fi

Custom Server Path

# Specify custom LSP server location
xs-lint --server /path/to/language-server/server.js

Output Examples

Human-Readable Output

src/api/users.xs:
  ❌ Line 12:5 - Unexpected token 'function'
     Code: unexpected-token
  ⚠️  Line 24:10 - Unused variable 'userId'

src/functions/helpers.xs:
  ❌ Line 8:15 - Invalid function syntax

────────────────────────────────────────────────────────────
📊 Summary:
   Files checked: 15
   Files with issues: 2
   ❌ Errors: 2
   ⚠️  Warnings: 1

JSON Output

{
  "summary": {
    "totalFiles": 15,
    "filesWithIssues": 2,
    "totalErrors": 2,
    "totalWarnings": 1,
    "totalInfo": 0,
    "hasErrors": true
  },
  "results": [
    {
      "file": "src/api/users.xs",
      "diagnostics": [
        {
          "line": 12,
          "column": 5,
          "severity": "error",
          "message": "Unexpected token 'function'",
          "code": "unexpected-token"
        }
      ],
      "errorCount": 1,
      "warningCount": 0
    }
  ]
}

Claude Code Integration

This CLI includes a built-in Claude Code slash command for AI-assisted debugging and error fixing.

Setup

The .claude/commands/xs-lint.md file is already included in the repository. Claude Code will automatically detect it when working in this directory or any XanoScript project.

Usage with Claude Code

/xs-lint

This will:

1. Run diagnostics on all .xs files
2. Analyze the errors
3. Automatically fix issues where possible
4. Re-validate to confirm fixes
5. Provide a summary of changes

You can also specify files:

/xs-lint src/api/users.xs

After installing the CLI inside a project workspace, run:

xs-setup --symlink

This links the .claude skill and command so future CLI updates propagate automatically to Claude Code and other compatible agents.

Exit Codes

• 0 - Success (no errors found)
• 1 - Errors found or validation failed

Perfect for CI/CD:

xs-lint || exit 1

How It Works

┌──────────────────┐
│  xs-lint CLI     │
│  (This Tool)     │
└────────┬─────────┘
         │ JSON-RPC over stdio
         │ (LSP Protocol)
┌────────▼─────────┐
│  XanoScript LSP  │
│  Server          │ ← From VS Code Extension
│  (server.js)     │
└──────────────────┘

The CLI:

1. Spawns the XanoScript LSP server from your VS Code extension
2. Sends standard LSP messages (initialize, textDocument/didOpen, textDocument/didChange)
3. Receives diagnostics via textDocument/publishDiagnostics
4. Formats and displays the results

Architecture

• bin/xs-lint.js - Main CLI entry point
• lib/lsp-client.js - LSP client wrapper
• lib/validator.js - File validation logic
• lib/formatters.js - Output formatting
• .claude/commands/xs-lint.md - Claude Code integration

Troubleshooting

"XanoScript extension not found"

Make sure you have the XanoScript VS Code extension installed:

code --install-extension xano.xanoscript

Or specify the server path manually:

xs-lint --server /path/to/server.js

"No .xs files found"

The CLI searches for files matching **/*.xs in the current directory. Make sure you're in the right directory or specify files explicitly:

xs-lint path/to/your/files/**/*.xs

LSP Server Errors

If you see LSP-related errors, try:

1. Updating the XanoScript VS Code extension
2. Restarting VS Code
3. Checking the server.js file exists at the expected location

Development

# Install dependencies
npm install

# Run locally
node bin/xs-lint.js

# Test with specific files
node bin/xs-lint.js test/**/*.xs

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT

Related Projects

• XanoScript VS Code Extension
• Xano Platform
• Language Server Protocol

Support

• GitHub Issues: Report a bug or request a feature
• Xano Community: community.xano.com