VS Code extension

Compile, preview, run and inspect Kater SQL in VS Code, Cursor or Windsurf, with the same panels as the portal.

Audience

Data teams

Prerequisites

VS Code, Cursor or Windsurf
The Kater CLI, signed in
A local copy of your content

The Kater extension brings the workspace editor into VS Code. Write Kater SQL with completion and diagnostics, run a query and see its rows and chart, and manage access to a folder, all next to your other files.

Install.

Run kater vscode install. It installs the extension, kater.kater, into each of VS Code, Cursor and Windsurf it finds on your PATH. VS Code gets it from the Visual Studio Marketplace, and Cursor and Windsurf get it from Open VSX. In an editor, you can also search the Extensions view for Kater SQL.
Open your content.

Open your local copy. The extension uses the first folder that holds connections/, or the folder in katerQuery.katerRoot.
Sign in.

Run Kater: Sign In. It signs you in through the browser, as kater login does, and keeps your tokens in VS Code’s secret storage. Kater: Sign Out clears them.

Panels

Panel	Where	What it shows
Kater	Bottom panel	The workspace editor for the open file: field picker, rows, chart, chart settings, SQL editor, lineage and compiled SQL.
Kater Logs	Bottom panel	Kater Logs: errors and run details.
Kater Sandbox	Bottom panel	Your scratch files and their statement results.
Kater Access	Explorer	Who has access to the open file, or to a folder you select with Kater: Manage Access….

Languages

Each Kater file type gets its own language, set from its path. The Kater language server gives each one diagnostics, hover, completion, go to definition, formatting and quick fixes. The extension starts it with the CLI that you installed, as kater lsp.

Language	Files
Kater Dataset	`modeling/kater_objects/datasets/*/.sql`
Kater Semantic Model	`modeling/kater_objects/semantic_models/*/.sql`
Kater Workspace	`workspaces/*/workspace.sql`
Kater Query Contract	`workspaces//query_contracts//.sql`
Kater Chart	`workspaces//charts//.sql`
Kater Test	`modeling/kater_objects/tests/.sql`, a workspace’s `tests/`, and `users//tests/`
Kater Scratch File	`users//brainstorm//.sql`

Commands

Every command starts with “Kater:” in the command palette.

Group	Commands
Run	Run, Run Tags, Compile Query, Refresh Data
Panels	Show Output, Show Field Picker, Show Logs, Show Sandbox, Show Editor, Show Dashboard, Show Workspace Definitions, Show Problems, and Show or Hide Field Picker, SQL Editor, Rows, Chart, Chart Settings, Lineage and Compiled SQL
Make	New Query, New Workspace, New App, New Chart, New Field, New Scratch File, Save as New Query, Duplicate Query
Sandbox	Open in Sandbox, Run Statement, Run All Statements
Tests	Run Test, Show Test SQL, Record Test Rows, Mark Test Checked, Generate Tests, Save Query as Test
Rows and fields	Copy Rows as CSV, Add Field, Add Filter, Top Rows and Row Limit, Find in Rows, Search Fields
Queries	Previous Query, Next Query, Move Query Left, Move Query Right, Delete Query, Add To, Promote a Field
History	Undo Last Change, Redo Last Change
Other	Ask, Compare, Open Page, Manage Access…, Sign In, Sign Out

In a scratch or test file, ⌘↵ runs the statement at the cursor and ⇧⌘↵ runs every statement. On Windows and Linux, use Ctrl in place of ⌘.

Settings

Setting	What it does	Default
`katerQuery.apiUrl`	The Kater API the Access view, brainstorm pages and Ask call	The address `kater login` saved
`katerQuery.authUrl`	The sign-in address	The one `kater login` saved
`katerQuery.authClientId`	The sign-in client id	The one `kater login` saved
`katerQuery.authRedirectUri`	Where the browser returns after sign-in	`http://127.0.0.1:8765/callback`
`katerQuery.webUrl`	The Kater web app that Copy link, Open in browser and Ask’s links point at	`https://app.kater.ai`
`katerQuery.katerRoot`	The absolute content root	The first folder that holds `connections/`
`katerQuery.serverCommand`, `serverArgs`	How to start the Kater language server	`kater lsp`
`katerQuery.cliCommand`, `cliArgs`	How to run kater CLI operations: compile, run, previews, edits and logs	`kater`
`katerQuery.envFile`	A dotenv file whose values override the environment of the CLI and the language server, such as `KATER_TARGET`. It never holds warehouse settings. Reload the window after a change.	None
`katerQuery.executionMode`	Run compiles and runs. Compile writes SQL without querying the warehouse.	`run`
`katerQuery.runTarget`	Query runs the whole query. Selected runs the nested query at the cursor.	`query`

Work between the portal and VS Code

Open links in VS Code. In the portal, set Profile › Links › Open links in to VS Code, or select Open in VS Code when a link asks. Citation links in exported files open the same way.
Scope follows your file. The Kater file you have open sets the scope for kater commands in the terminal.
Kater runs the warehouse queries. The extension compiles a query on your computer, with a kater process that it starts for the window. It sends the SQL to Kater, and Kater runs it on the warehouse with your organisation’s stored credential. Your computer never holds a warehouse credential, and katerQuery.envFile holds none.

Next steps

Set up the VS Code extension: install, sign in and the panels, with screenshots
Work in a local copy
Kater SQL reference