turbo-editors/turbo-js · cli.md

⑂ v1.0.3

cli.md · 119 lines · 7.2 KBmarkdown    Blame HistoryRaw
   1# Reference: command line
3> Neutral description of the `turbo-js` command, its flags, and the environment it reads.
5## Synopsis
8turbo-js [flags] [file...]
11Each `file` is opened in its own window. A file that does not exist yet is opened as an empty buffer bound to that path. With no file at all, one empty untitled window is opened.
Flag | Type | Default | Description |
--- | --- | --- | --- |
`-theme <name>` | string | the project's, else `turbo-classic` | Theme to start with, overriding the project's own. An unknown name falls back to the default without an error. |
`-list-themes` | bool | `false` | Print every loadable theme with its description, then the user theme directory, and exit. |
`-no-lsp` | bool | `false` | Do not start a language server. Colouring and editing are unaffected. |
`-version` | bool | `false` | Print `Turbo JS <version>` on one line, with the commit and build date when the build recorded them, and exit. See [the version number](versioning.md). |
`-load-config <url>` | string | none | Copy the `.turbo-js` directory found at a repository URL — rickub, GitHub, GitLab or Codeberg, the URL of the directory as the browser shows it — into the working directory, print what arrived, and exit. Needs `git`. Refuses when `./.turbo-js` already exists. The editor is not started. |
`-h`, `-help` | bool | `false` | Print the flag list and exit. |
24## Environment
Variable | Read by | Effect |
--- | --- | --- |
`TURBO_JS_DIR` | user files | Directory to keep the user's own files in — themes and snippets — instead of `~/.config/turbo-js`. |
`TURBO_JS_THEME_DIR` | theme loading | Directory to read user themes from, instead of `<user dir>/themes`. |
`TURBO_JS_SNIPPET_DIR` | snippets | Directory to read the user's `snippets.toml` from, instead of `<user dir>`. |
`TERM` | tcell | Which terminal description to use. |
`PATH` | `typescript-language-server` lookup | Searched first for `typescript-language-server`; the directories the variables below name are tried after it, then `/usr/local/bin` and `/opt/homebrew/bin`. |
`NVM_BIN`, `NPM_CONFIG_PREFIX`, `PNPM_HOME`, `VOLTA_HOME` | `typescript-language-server` lookup | Each names one more directory to look in, when set and non-empty: `$NVM_BIN`, `$NPM_CONFIG_PREFIX/bin` (else `~/.npm-global/bin`), `$PNPM_HOME`, `$VOLTA_HOME/bin` (else `~/.volta/bin`). |
Path | Purpose |
--- | --- |
`$TURBO_JS_THEME_DIR/*.toml` | User themes, when the variable is set. |
`./.turbo-js/settings.toml` | This project's settings, read at start-up and again when saved from the editor. See [project settings](project-settings.md). |
`./.turbo-js/` (written) | Created by `-load-config` from a repository's copy, when the project has none yet. |
`./.turbo-js/snippets.toml` | This project's snippets, read each time the Snippets menu opens. See [snippets](snippets.md). |
`./.turbo-js/tools.toml` | This project's tools, read each time the JavaScript menu opens. See [JavaScript tools](javascript-tools.md). |
`~/.config/turbo-js/themes/*.toml` | User themes on Linux (`os.UserConfigDir`). |
`~/.config/turbo-js/snippets.toml` | User snippets on Linux. |
`~/Library/Application Support/turbo-js/…` | The same two on macOS. |
`<project>/package.json` | The project marker: located by walking up from the first file; its directory becomes the language server's root. |
49`package.json` is the project marker. The language server is started in the nearest directory holding one, at or above the directory of the first file named on the command line — the working directory when none is; in a monorepo the nearest `package.json` wins. With none anywhere, it is started in that starting directory.
51## Exit status
Status | Meaning |
--- | --- |
`0` | The editor exited normally, or an informational flag was used. |
`1` | The terminal could not be opened or initialised. The reason is printed to standard error. |
58## Make targets
60Run from a checkout.
Target | What it runs |
--- | --- |
`make help` | List the targets. This is the default. |
`make test` | `go test ./...` |
`make test-verbose` | `go test -v ./...` |
`make cover` | `go test -cover ./...` |
`make build` | `go build -ldflags "…" -o bin/turbo-js .`, stamping the version, then `scripts/check-version.sh` on the result |
`make version` | Print the version this checkout would stamp, without building |
`make ldflags` | Print the linker flags a stamped build uses |
`make install` | `scripts/install.sh` — build and install onto your PATH |
`make uninstall` | `scripts/install.sh --uninstall` |
`make run FILE=x.js` | `make build`, then `./bin/turbo-js x.js` |
`make fmt` | `go fmt ./...` |
`make vet` | `go vet ./...` |
`make check` | `fmt`, then `vet`, then `test` |
`make clean` | Remove `bin/` |
79## Examples
82turbo-js                                    # one empty window
83turbo-js main.js main.test.js           # two windows
84turbo-js -theme turbo-dark main.js        # a different theme
85turbo-js -no-lsp main.js                  # no language server
86turbo-js -list-themes                       # what themes exist
   87turbo-js -load-config https://rickub.com/turbo-editors/configs/tree/main/golang-init  # start from a shared configuration
   88
90## Installer
92`scripts/install.sh`, also reachable as `make install`.
Option | Description |
--- | --- |
`-p`, `--prefix DIR` | Install into `DIR` instead of `$GOBIN` or `$GOPATH/bin`. |
`--with-server` | Also install the language server — `typescript-language-server` and TypeScript 6, with `npm install -g typescript-language-server typescript@6` — if a working one is not already found. Needs `npm`. |
`--uninstall` | Remove an installed `turbo-js` and stop. |
`-h`, `--help` | Print the options and stop. |
Exit status | Meaning |
--- | --- |
`0` | Installed, removed, or help printed. |
`1` | Go missing or too old, the build failed, the built binary did not report its version, or the destination could not be written. Nothing is installed and an existing installation is left untouched. |
`1`, after `Installing into …` | With `--with-server`: npm is missing, or `npm install -g` failed. The editor is installed; only the server is not. |
107
Message | Cause |
--- | --- |
`turbo-js: opening the terminal: …` | tcell could not open the terminal; usually `TERM` is unset or unknown. |
`turbo-js: initialising the terminal: …` | The terminal was opened but could not be put into raw mode. |
`turbo-js: reading …/settings.toml: …` | The project's settings file is not valid; the editor opens with its defaults. |
`Cannot open` (in a dialog) | The path is a directory, or is not readable. |
`Cannot save` (in a dialog) | The directory does not exist, or is not writable. |
`turbo-js: configrepo: the project already has a configuration directory: …` | `-load-config` into a project that already has `.turbo-js`. Move it away first. |
`turbo-js: configrepo: git is not installed` | `-load-config` needs the `git` command on `PATH`. |
`turbo-js: configrepo: no configuration directory at that path: …` | The repository was found but holds no `.turbo-js` where the URL points. |
`turbo-js: configrepo: no repository answered: …` | No clone address for that URL answered; the URL, the network, or a private repository. |

📦 Turbo JS 91999d1 k33g 22h ago	1	# Reference: command line
	2
	3	> Neutral description of the `turbo-js` command, its flags, and the environment it reads.
	4
	5	## Synopsis
	6
	7	```
	8	turbo-js [flags] [file...]
	9	```
	10
	11	Each `file` is opened in its own window. A file that does not exist yet is opened as an empty buffer bound to that path. With no file at all, one empty untitled window is opened.
	12
	13	## Flags
	14
	15	\| Flag \| Type \| Default \| Description \|
	16	\| --- \| --- \| --- \| --- \|
	17	\| `-theme <name>` \| string \| the project's, else `turbo-classic` \| Theme to start with, overriding the project's own. An unknown name falls back to the default without an error. \|
	18	\| `-list-themes` \| bool \| `false` \| Print every loadable theme with its description, then the user theme directory, and exit. \|
	19	\| `-no-lsp` \| bool \| `false` \| Do not start a language server. Colouring and editing are unaffected. \|
	20	\| `-version` \| bool \| `false` \| Print `Turbo JS <version>` on one line, with the commit and build date when the build recorded them, and exit. See [the version number](versioning.md). \|
📦 Turbo JS 27bdf0b k33g 2h ago	21	\| `-load-config <url>` \| string \| none \| Copy the `.turbo-js` directory found at a repository URL — rickub, GitHub, GitLab or Codeberg, the URL of the directory as the browser shows it — into the working directory, print what arrived, and exit. Needs `git`. Refuses when `./.turbo-js` already exists. The editor is not started. \|
📦 Turbo JS 91999d1 k33g 22h ago	22	\| `-h`, `-help` \| bool \| `false` \| Print the flag list and exit. \|
	23
	24	## Environment
	25
	26	\| Variable \| Read by \| Effect \|
	27	\| --- \| --- \| --- \|
	28	\| `TURBO_JS_DIR` \| user files \| Directory to keep the user's own files in — themes and snippets — instead of `~/.config/turbo-js`. \|
	29	\| `TURBO_JS_THEME_DIR` \| theme loading \| Directory to read user themes from, instead of `<user dir>/themes`. \|
	30	\| `TURBO_JS_SNIPPET_DIR` \| snippets \| Directory to read the user's `snippets.toml` from, instead of `<user dir>`. \|
	31	\| `TERM` \| tcell \| Which terminal description to use. \|
	32	\| `PATH` \| `typescript-language-server` lookup \| Searched first for `typescript-language-server`; the directories the variables below name are tried after it, then `/usr/local/bin` and `/opt/homebrew/bin`. \|
	33	\| `NVM_BIN`, `NPM_CONFIG_PREFIX`, `PNPM_HOME`, `VOLTA_HOME` \| `typescript-language-server` lookup \| Each names one more directory to look in, when set and non-empty: `$NVM_BIN`, `$NPM_CONFIG_PREFIX/bin` (else `~/.npm-global/bin`), `$PNPM_HOME`, `$VOLTA_HOME/bin` (else `~/.volta/bin`). \|
	34
	35	## Files
	36
	37	\| Path \| Purpose \|
	38	\| --- \| --- \|
	39	\| `$TURBO_JS_THEME_DIR/*.toml` \| User themes, when the variable is set. \|
	40	\| `./.turbo-js/settings.toml` \| This project's settings, read at start-up and again when saved from the editor. See [project settings](project-settings.md). \|
📦 Turbo JS 27bdf0b k33g 2h ago	41	\| `./.turbo-js/` (written) \| Created by `-load-config` from a repository's copy, when the project has none yet. \|
📦 Turbo JS 91999d1 k33g 22h ago	42	\| `./.turbo-js/snippets.toml` \| This project's snippets, read each time the Snippets menu opens. See [snippets](snippets.md). \|
	43	\| `./.turbo-js/tools.toml` \| This project's tools, read each time the JavaScript menu opens. See [JavaScript tools](javascript-tools.md). \|
	44	\| `~/.config/turbo-js/themes/*.toml` \| User themes on Linux (`os.UserConfigDir`). \|
	45	\| `~/.config/turbo-js/snippets.toml` \| User snippets on Linux. \|
	46	\| `~/Library/Application Support/turbo-js/…` \| The same two on macOS. \|
	47	\| `<project>/package.json` \| The project marker: located by walking up from the first file; its directory becomes the language server's root. \|
	48
	49	`package.json` is the project marker. The language server is started in the nearest directory holding one, at or above the directory of the first file named on the command line — the working directory when none is; in a monorepo the nearest `package.json` wins. With none anywhere, it is started in that starting directory.
	50
	51	## Exit status
	52
	53	\| Status \| Meaning \|
	54	\| --- \| --- \|
	55	\| `0` \| The editor exited normally, or an informational flag was used. \|
	56	\| `1` \| The terminal could not be opened or initialised. The reason is printed to standard error. \|
	57
	58	## Make targets
	59
	60	Run from a checkout.
	61
	62	\| Target \| What it runs \|
	63	\| --- \| --- \|
	64	\| `make help` \| List the targets. This is the default. \|
	65	\| `make test` \| `go test ./...` \|
	66	\| `make test-verbose` \| `go test -v ./...` \|
	67	\| `make cover` \| `go test -cover ./...` \|
	68	\| `make build` \| `go build -ldflags "…" -o bin/turbo-js .`, stamping the version, then `scripts/check-version.sh` on the result \|
	69	\| `make version` \| Print the version this checkout would stamp, without building \|
	70	\| `make ldflags` \| Print the linker flags a stamped build uses \|
	71	\| `make install` \| `scripts/install.sh` — build and install onto your PATH \|
	72	\| `make uninstall` \| `scripts/install.sh --uninstall` \|
	73	\| `make run FILE=x.js` \| `make build`, then `./bin/turbo-js x.js` \|
	74	\| `make fmt` \| `go fmt ./...` \|
	75	\| `make vet` \| `go vet ./...` \|
	76	\| `make check` \| `fmt`, then `vet`, then `test` \|
	77	\| `make clean` \| Remove `bin/` \|
	78
	79	## Examples
	80
	81	```bash
	82	turbo-js # one empty window
	83	turbo-js main.js main.test.js # two windows
	84	turbo-js -theme turbo-dark main.js # a different theme
	85	turbo-js -no-lsp main.js # no language server
	86	turbo-js -list-themes # what themes exist
📦 Turbo JS 27bdf0b k33g 2h ago	87	turbo-js -load-config https://rickub.com/turbo-editors/configs/tree/main/golang-init # start from a shared configuration
📦 Turbo JS 91999d1 k33g 22h ago	88	```
	89
	90	## Installer
	91
	92	`scripts/install.sh`, also reachable as `make install`.
	93
	94	\| Option \| Description \|
	95	\| --- \| --- \|
	96	\| `-p`, `--prefix DIR` \| Install into `DIR` instead of `$GOBIN` or `$GOPATH/bin`. \|
	97	\| `--with-server` \| Also install the language server — `typescript-language-server` and TypeScript 6, with `npm install -g typescript-language-server typescript@6` — if a working one is not already found. Needs `npm`. \|
	98	\| `--uninstall` \| Remove an installed `turbo-js` and stop. \|
	99	\| `-h`, `--help` \| Print the options and stop. \|
	100
	101	\| Exit status \| Meaning \|
	102	\| --- \| --- \|
	103	\| `0` \| Installed, removed, or help printed. \|
	104	\| `1` \| Go missing or too old, the build failed, the built binary did not report its version, or the destination could not be written. Nothing is installed and an existing installation is left untouched. \|
	105	\| `1`, after `Installing into …` \| With `--with-server`: npm is missing, or `npm install -g` failed. The editor is installed; only the server is not. \|
	106
	107	## Errors
	108
	109	\| Message \| Cause \|
	110	\| --- \| --- \|
	111	\| `turbo-js: opening the terminal: …` \| tcell could not open the terminal; usually `TERM` is unset or unknown. \|
	112	\| `turbo-js: initialising the terminal: …` \| The terminal was opened but could not be put into raw mode. \|
	113	\| `turbo-js: reading …/settings.toml: …` \| The project's settings file is not valid; the editor opens with its defaults. \|
	114	\| `Cannot open` (in a dialog) \| The path is a directory, or is not readable. \|
	115	\| `Cannot save` (in a dialog) \| The directory does not exist, or is not writable. \|
📦 Turbo JS 27bdf0b k33g 2h ago	116	\| `turbo-js: configrepo: the project already has a configuration directory: …` \| `-load-config` into a project that already has `.turbo-js`. Move it away first. \|
	117	\| `turbo-js: configrepo: git is not installed` \| `-load-config` needs the `git` command on `PATH`. \|
	118	\| `turbo-js: configrepo: no configuration directory at that path: …` \| The repository was found but holds no `.turbo-js` where the URL points. \|
	119	\| `turbo-js: configrepo: no repository answered: …` \| No clone address for that URL answered; the URL, the network, or a private repository. \|