https://github.com/cursorless-dev/talon-tools
Linting and formatting tools for Talon and Cursorless
https://github.com/cursorless-dev/talon-tools
Last synced: about 2 months ago
JSON representation
Linting and formatting tools for Talon and Cursorless
- Host: GitHub
- URL: https://github.com/cursorless-dev/talon-tools
- Owner: cursorless-dev
- License: mit
- Created: 2026-03-08T16:04:56.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-23T12:50:12.000Z (2 months ago)
- Last Synced: 2026-03-24T07:26:53.335Z (2 months ago)
- Language: TypeScript
- Size: 1010 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Talon tools
Linting and formatting tools for Talon and Cursorless.
## Installation
### Local dev dependency
Install the package in your project:
```sh
npm install --save-dev @cursorless/talon-tools
```
Run the local CLI commands with `npx`:
```sh
npx talon-fmt [options] [file/dir/glob ...]
npx snippet-fmt [options] [file/dir/glob ...]
npx tree-sitter-fmt [options] [file/dir/glob ...]
```
### Global install
Install the binaries globally:
```sh
npm install --global @cursorless/talon-tools
```
Run the binaries directly:
```sh
talon-fmt [options] [file/dir/glob ...]
snippet-fmt [options] [file/dir/glob ...]
tree-sitter-fmt [options] [file/dir/glob ...]
```
## CLI options
All binaries support these options:
| Option | Meaning |
| ----------- | -------------------------------- |
| `--help` | Show help |
| `--version` | Show version |
| `--quiet` | Suppress non-error output |
| `--check` | Check formatting without writing |
| `--debug` | Print debug output |
Use `--debug` when diagnosing parser or formatter support for new syntax.
## Formatting options
Formatting options are read from [.editorconfig](https://editorconfig.org) based on the file path being
formatted. For stdin, the formatter resolves a synthetic file such as
`stdin.talon`, `stdin.talon-list`, `stdin.scm`, or `stdin.snippet` from the
current working directory and loads `.editorconfig` relative to that path.
Supported `.editorconfig` properties:
| Property | Meaning | Default | `talon-fmt` | `snippet-fmt` | `tree-sitter-fmt` |
| ---------------------- | ----------------------------------- | -------- | ----------- | ------------- | ----------------- |
| `end_of_line` | Set output line endings | `lf` | yes | yes | yes |
| `indent_style` | Use tabs or spaces for indentation | `spaces` | yes | no | yes |
| `indent_size` | Set indentation width | `4` | yes | no | yes |
| `max_line_length` | Set preferred maximum line width | `80` | yes | no | no |
| `insert_final_newline` | Ensure the file ends with a newline | `true` | yes | yes | yes |
| `preserve_multiline` | Keep existing multi-line formatting | `false` | yes | no | no |
| `column_width` | Set aligned left-column width | | yes | no | no |
Use `--` to mark the end of options. Any following arguments are treated as
file, directory, or glob patterns even if they start with `--`.
```sh
talon-fmt -- --check
```
### Column width comment
The column width option can be enabled on a per file basis using a fmt comment.
```talon
# fmt: columnWidth=15
foo: "foo"
foo bar baz: "foo bar baz"
```
## Exit codes
| Code | Information |
| ---- | ----------------------------------- |
| 0 | Everything formatted properly |
| 1 | Something wasn't formatted properly |
| 2 | Runtime error |
## Pre commit
```yaml
repos:
- repo: https://github.com/cursorless-dev/talon-tools
rev: v0.10.0
hooks:
- id: talon-fmt
- id: snippet-fmt
- id: tree-sitter-fmt
```
## Guidelines
- Each pre-commit hook should have a matching npm binary with the same name.
- Binaries ending with `-fmt` are formatters by default and turn into linters/checkers with the `--check` argument.
- (Future) binaries ending with `-check` are linters by default and turn into fixers with the `--fix` argument.
## Developer
```sh
# Try formatter without pre-commit
node dist/talonFormatter.js test.talon
# Try formatter with pre-commit
pre-commit try-repo . talon-fmt --files test.talon -v
```
Install the hooks locally:
```yaml
# .pre-commit-config.yaml
repos:
- repo: .
rev: HEAD
hooks:
- id: talon-fmt
- id: snippet-fmt
- id: tree-sitter-fmt
```
```sh
pre-commit install
pre-commit run --all-files
```
## Release
When creating a new release do the following:
- Update version in [`package.json`](./package.json)
- Update version in [`README.md`](./README.md#pre-commit)
- Run build: `npm run build`
- Add new tag eg `git tag v1.2.0`
- Publish lib: `npm publish --access public`