Keysharp executes plain-text scripts written in its AutoHotkey v2-compatible language. Use .ks for an explicitly Keysharp script or .ahk when compatibility with AutoHotkey-oriented tools is useful. Compiled Keysharp assemblies use .cks.
#z::Run "https://github.com/keysharp-org/Keysharp" ; Win+Z
^!n:: ; Ctrl+Alt+N
{
if WinExist("Untitled - Notepad")
WinActivate
else
Run "Notepad"
}
hello.ks.Keyview, which is distributed with Keysharp, shows the generated C# and validation feedback while editing, and can run and compile the script.
See Install Keysharp for supported installers, portable layouts, source builds, platform prerequisites and uninstall instructions.
On Windows, extract the portable ZIP and run Keysharp.exe directly; see the portable Windows instructions. On Linux, run app/Keysharp from the extracted archive; see Installing without root.
Keysharp does not provide UI-access executables. To automate an elevated window, run the script at a sufficient integrity level.
The Dash is a launcher for creating a script from a template, running an existing one, and opening the bundled tools and demos.
Use --transpile to write the generated C# without running the script, or a --compile mode to write a reusable assembly or executable.
Diagnostic output which reports managed types, such as the types shown by ListVars, can show implementation names for some built-in classes: KeysharpObject for Object, KeysharpFile for File, KeysharpFunc for Func, and StructInt32 and so on for the numeric struct types. Scripts use only the documented names, which Type reports.
Pass the script path to the Keysharp executable:
Keysharp.exe hello.ks
On Linux or a user-local command installation:
keysharp hello.ks
Quote paths containing spaces. Arguments after the script path are made available to the script through A_Args.
Keysharp.exe "C:\My Scripts\hello.ks" first "second argument"
Started with no script at all, Keysharp looks for one named after its own executable — Keysharp.ahk, then Keysharp.ks, then Keysharp.cks — first in the working directory and then beside the executable. Release packages include the Dash as Keysharp.cks at the install root, so a bare launch opens it unless a matching script of your own is found first.
Options must appear before the script or assembly input. After the input is found, all remaining arguments are passed to its entry point. Options can begin with - or --; AutoHotkey-compatible run options can also begin with / on Windows. The AutoHotkey-compatible options are described in Passing Command Line Parameters to a Script.
| Option | Behavior |
|---|---|
--define:NAME[,NAME...] | Predefine conditional-compilation symbols. Repeatable, and also applied to any module the script imports. A symbol carries no value, so the name must be a plain identifier. |
--validate | Parse and compile the source without running it. |
--validate-syntax | Parse the source without lowering, compiling or loading Roslyn. --syntax-only and --parse-only are aliases. |
--transpile | Write generated C# beside the source and do not run the script. |
--compile, --compile asm or --compile dll | Write a raw compiled .cks assembly. asm and dll are aliases. Several scripts may follow, each compiled to a .cks beside its own source. This is faster than running one command per script. A script using #Package also writes its private .keysharp/packages hierarchy. Runtime Clr.LoadPackage calls use the provider installed with the launcher. |
--compile exe | Build a standalone executable which still requires .NET 10. A script using #Package carries its assets in a private .keysharp/packages hierarchy beside the output. Statically visible Clr.LoadPackage use carries its runtime provider under components/packages/<name>. |
--compile exe-min | Build an executable with dependencies, including #Package assets and statically required package providers, embedded in the generated DLL. Embedded providers are verified and extracted on first use. The result consists of the executable, DLL, Keysharp.Core DLL, deps file and runtime-config file. |
--dest <path> | Select the output file or directory for a compile operation. For assembly output, * writes the bytes to standard output. It accepts only one script. |
--with-parser, --with-compiler | Include the selected optional first-party deployment unit in a compiled artifact. |
--with-component <parser|compiler> | Generic form of the two unit-inclusion options. |
--without-parser, --without-compiler | Exclude the selected component, including one detected from a call in the script. |
--without-component <parser|compiler> | Generic form of the two component-exclusion options. |
--asm, --assembly | Run a precompiled assembly from a file or from standard input (*). A .cks or .dll input is recognized without this option. |
--asm:Namespace.Type.Method | Run a precompiled assembly with a custom entry point, splitting the type and method at the final dot. |
--daemon | Start the background compile server. |
--daemon stop | Stop the running compile server. |
--daemon ping <script> | Ask a running daemon to compile the script and report the result without running it. |
--version, -v | Print the version. |
--about | Print license information. |
--help, -h, -? | Show command-line help. |
Release builds use the compile daemon for ordinary source runs by default; Debug builds do not. Set KEYSHARP_DAEMON to 1, true, yes or on to force it, or 0, false, no or off to bypass it.
The daemon runs unelevated; the requesting process runs the compiled script with its own privileges. On Windows, an elevated launcher can use its account's authenticated, unelevated daemon. If a normal daemon cannot start, or an elevated request fails to compile, the launcher compiles locally with its existing permissions. On Linux and macOS, a privileged launcher compiles locally instead of starting a privileged daemon.
Keysharp.exe --compile exe hello.ks
The parser and compiler are optional components. A compiled script includes the compiler when it makes a statically visible call to RunScript or CompileScript, and the parser when it makes one to ValidateScript; otherwise it includes neither. The parser alone is sufficient for --validate-syntax. Use the --with-* options for explicit inclusion, or --without-* to override detection when code checks IsComponentAvailable and has a compiler-free path.
A normal executable or .cks deploys the selected components below components/scripting; a minimal executable embeds them and extracts them to the per-user component cache on first use.
A compiled executable normally runs its embedded script. Pass --script and a source-script path to run that script in place of the embedded one; remaining arguments are passed to the selected script.
On supported desktop platforms, a persistent script can expose a notification-area icon and menu. Functions such as Pause, Suspend, Reload, and ExitApp control the running script.
The standard menu includes Help, Window Spy, Reload Script, Edit Script, Suspend Hotkeys, Pause Script and Exit. On Windows, Help opens the Keysharp project repository; on Linux and macOS, it opens the issue tracker. On Linux and macOS it also includes an Accessibility Spy item.
The script main window provides views of debug output, variables, hotkeys and key history. Open it from the standard tray menu when A_AllowMainWindow permits it. A_ScriptHwnd identifies the window.
The views are snapshots of the current runtime state and refresh when selected. Functions such as ListVars, ListHotkeys and KeyHistory select related views.
The main window's default title is the script name. Single-instance detection uses this window and title, so changing or destroying the main window can prevent a later launch from identifying the existing instance.
Window Spy is a bundled script which reports window titles, classes, process information, controls, coordinates and colors. Launch it from the standard tray menu or the script main window.
On Linux, Accessibility Spy launches AtSpi.ks. On macOS it launches Ax.ks.
Language parsing and general runtime behavior are intended to be cross-platform, but window management, keyboard hooks, COM, registry access, GUI behavior, and other operating-system integrations can differ. See Platform Support and each affected reference page.