 # ✨ Script Kit 2.0 ✨

**Download for your platform from [scriptkit.com](https://scriptkit.com)**

## ⭐️ Unlock Script Kit Pro by Sponsoring Script Kit ⭐️

❤️ [Sponsor me on GitHub](https://github.com/sponsors/johnlindquist/sponsorships?sponsor=johnlindquist&tier_id=235205) ❤️

## New Main Menu

The main menu has been re-designed and optimized for your keyboard-centric workflows.

<img width="827" alt="CleanShot 2023-10-27 at 07 47 09@2x" src="https://github.com/johnlindquist/kit/assets/36073/60b9d227-d0a1-4cf0-ae2a-bede13fba9ef">

## Default to TypeScript

Script Kit now defaults to TypeScript for all new scripts. While v1 experienced issues with watching/compiling .ts files, we now have a custom loader that eliminates the need to watch .ts files for changes.

An awesome benefit of this is you can create a script anywhere on your system, such as `~/Desktop/my-script.ts` (or js if you prefer) and run it from script runner: `~/.kit/bin/kit ~/Desktop/my-script.ts`.

> Note: Your IDE won't recognize the `import` statements since it's not in a project, but the script will run just fine.

If we get enough requests, we will allow you to run the scripts from the built-in file browser through the app as well.

## Watch Scripts Imports for npm Install

As you're writing your scripts in your favorite editor, Kit.app will detect "on save" if you've added a new npm package and automatically prompt you to install it using the Kit.app built-in terminal.

## Windows and Linux arm64 Support

Script Kit now works on arm64 Windows and Linux. Almost all features are supported, but we did have to remove the keyboard listener as the library we use doesn't support arm64 yet. We'll keep investigating this.

## New Custom Windows

### Mac
Prompts like `editor` and `term` which use `ignoreBlur` will now convert the window into an "app" window which can be accessed by `cmd+tab`, is pinned when switching spaces, and shows up in Mission Control. This is also forward-looking to v3 which I'll talk about more in the future...

### Windows 

We built a custom Windows window to match the osx window behavior. We overrode all the maximize/minimize animations and the close buttons so it will instantly open and close. This makes the entire experience feel much closer to what osx users are used to.

## Keywords
Borrowed directly from Alfred, keywords allow you to trigger a script by typing a keyword followed by a space.

A keyword can be a single character or a word. For example, `c` for `clipboard`.

### Built-in Keywords
- `s` - Displays Snippets from your Snippets Directory
- `c` - Displays Clipboard History
- `f` - Find script by searching script contents
- `kit` - Access kit settings
- `kenv` - Access kenv options
- `npm` - Add/remove npm packages
- `spell` - List spelling suggestions for the input
 
 And many others. To see them all, type `keyword` into the Script Kit prompt.

 To create a custom keyword for your own scripts, add:

 ```
 // Keyword: mycustomkeyword
 ```

 If the first prompt is an `await arg()`, it will display the list in the main menu. Otherwise, it will jump to the next prompt.

 Also, if the first prompt is a static list and you shave off the few milliseconds required to load the list from your script, you can cache the list (after the first run) by adding:

 ```
 // Cache: true
 ```

Use caching sparingly, as it's only useful for `// Keyword` and `// Shortcut` where the first prompt is an `arg` with a static list.

## Pass Main Menu Input to a Script

```
// Pass: true
```

The `Pass` metadata allows you to type into the main menu without your script being filtered out of the list. Once you select the script, the input you've typed will be "passed" into the script. You can access the "passed" input using `flag?.pass`. For example, if you want to pass the main menu input to the input of you first arg:

```
// Name: Pass Demo
// Pass: true

import "@johnlindquist/kit"

await arg({
  input: flag?.pass || "",
})
```

### Pass "postfix"

Image you want to type: "How many moons does Jupiter have?" and have the "?" automatically trigger a script that reaches out to an AI service. You can do this by adding a "postfix" to the `Pass` metadata.

```
// Pass: ?
```

This will automatically trigger the script when you type a "?" at the end in the main menu and the entire input will be passed to the script as `flag?.pass`.

## Multi-select Prompt `await select()`

<img width="833" alt="CleanShot 2023-10-27 at 15 26 56@2x" src="https://github.com/johnlindquist/kit/assets/36073/9420d7a8-096c-468b-b98c-a9f70b48569b">

```js
let arrayOfChoices = await select("Pick one or more", ["one", "two", "three"])
```

Probably the most requested feature, Script Kit now has a `select` prompt which allows you to pick multiple choices.

## Themes Per Light/Dark Mode

You can now customize which theme will be active for both light and dark more or use the same theme for both.

## Snippets Directory

In your ~/.kenv/snippets directory, create .txt files you want to use as snippets. For example:
1. Create `~/.kenv/snippets/lorem.txt`
2. Add the following text to the file:
```
// Name: Lorem Ipsum
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
```

The "Lorem Ipsum" snippet will now appear in the Snippets menu using the `s` keyword. Select the snippet will paste it into the current application.

Adding Snippet metadata will allow you to invoke the snippet anywhere on your system. It's a best practice to use a "postfix", such as ",,", to avoid triggering the snippet when you don't want to.
```
// Snippet: lorem,,
```

### Snippet Creator

<img width="829" alt="CleanShot 2023-10-27 at 01 02 25@2x" src="https://github.com/johnlindquist/kit/assets/36073/a32d5e12-8ff2-441c-8edf-cfdfe3b1ab0d">

Typing `ns ` from the main menu will launch the quick snippet creator. There's a helpful guide there that will show all the available options. Just to list a few:

- Tab stops: $0, $1, $2, $3
- Dropdown list: ${|apple,banana,cherry|}
- Current selection: $SELECTION
- Clipboard content: $CLIPBOARD

and many more...

If you need more advanced scenarios, for example clipboard history:

```js
let history = await getClipboardHistory()
let text = await arg("Pick an item from your history", history.map(item => item.value)

let result = await template(`Hello $0,

${text}
`)

await writeFile(home("example.txt"), result)
```

## Actions

The new `actions` array makes it much easier to assign shortcuts and behaviors when you have a choice selected. You can access the actions menu by pressing `right`on the keyboard, then quickly search to execute the action you want to take with the currently focused choice:

```js
// Name: Actions Example

import { Action } from "@johnlindquist/kit"

// Using a "flag" determines where to do to custom logic: After the prompt or in the action
// Also, "flags" are supported when running the script in the terminal with `--js`
let actions: Action[] = [
  {
    shortcut: `${cmd}+t`,
    name: "Append .ts",
    visible: true, // Display shortcut in the prompt
    onAction: async (input, state) => {
      // Since we're not using a "flag", we can do custom logic here
      submit(`${state.focused?.name}.ts`)
    },
  },
  {
    name: "Append .js",
    flag: "js", // Set `global.flag.js` to true when selecting the action
  },
]

let result = await arg("Pick a number", ["one", "two", "three"], actions)

if (flag.js) {
  result = `${result}.js`
}

inspect(result)
```

## Previews on All Prompts

You can build-out helpful previews on the right side for all prompts now (see the Snippet Creator above for a great example). This is especially useful for prompts like `editor`, `drop`, and `term` where you may need reminders on what the script is doing or steps you want to guide the user through.

```js
await editor({
  value: `Book Outline`,
  preview: md(`# Requirements
- Cover Major Characters
- Address the theme
- Have a beginning, middle, and end  
  `),
})
```


## Move kenv to a Different Directory

Type `kit move` into the main prompt to move your kenv directory to a different location. This is useful if you want to keep your scripts in dotfiles or other setup.

## Built-in Guide, API, and Tips Keywords

From the main menu, type `guide`, `api`, or `tips` to immediately launch into helpful information.

From the `api` list, pressing `cmd+p` will create a demo script with the examples shown so you can instantly start playing around with the various APIs.

![CleanShot 2023-12-14 at 08 28 39@2x](https://github.com/johnlindquist/kit/assets/36073/a088616d-6cc5-4723-8dcf-9173943609b8)

> Note: These are living documents parsed from the markdown files over at https://github.com/johnlindquist/kit-docs . So you can expect updates and new demos as we add more and more.

## New APIs

We'll follow-up with individual posts and demos around the new available APIs. Lots of new goodies to play with :)


## Road to v3

The major plan for v3 is enabling you to run multiple scripts each with their own editor/terminal/etc (this was a big reason we had to build custom windows mentioned above). We've only just begun toying with the implementation, so don't expect much news on it until sometime next year. Lots of other goodies planned too! We're super excited to keep pushing Script Kit forward.

## Questions?

Please ask below or join our [Discord](https://discord.gg/77MdcpSW) We're always happy to help figure out better workflows to optimize your day. Happy scripting!

\- John