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 is distributed with Keysharp and provides a convenient Keysharp-oriented viewer/editor. AutoHotkey v2 editor extensions can also provide useful syntax highlighting because the languages are intentionally compatible, although their launch and debugging integration may require configuration.
Keyview displays generated C# and validation feedback while editing, and can open, save, run and compile source files. Its editor features are still developing.
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. Linux source builds and macOS source archives can likewise run from their build or extracted directories after their platform prerequisites are installed.
Install a newer release using the same method as the original installation. Check the Keysharp releases and read Recent Changes before replacing an existing installation.
Keysharp executables do not use a Windows uiAccess manifest. AutoHotkey instructions which rely on an installed UI-access executable therefore do not apply. To automate an elevated target, run the script at a sufficient integrity level and consider the security implications before doing so.
Keysharp does not include AutoHotkey Dash. Use Keyview or a configured text editor to create, inspect and run scripts. References to Dash which remain in inherited AutoHotkey compatibility material describe an AutoHotkey tool, not part of the Keysharp distribution.
This differs from a traditional interpreter: script code executes as a compiled .NET program. Use --transpile to write the generated C# without running the script, or a --compile mode to write a reusable assembly or executable.
Some built-in classes carry a different name in the compiled assembly, because the documented name collides with a .NET framework type: Object is implemented as KeysharpObject, File as KeysharpFile and Func as KeysharpFunc. The numeric struct types are similarly implemented as StructInt32 and so on.
Only the documented names are valid in script code; the internal names are not class names a script can use, and Type reports the documented name. The internal names can still appear in diagnostic output that reports managed types directly, such as the call frames of Error.Stack or the type shown for a variable by ListVars. Read them as the documented class of the same name.
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"
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.
| Option | Behavior |
|---|---|
--script | In a compiled executable, ignore the embedded script and run the source script supplied as the input. |
--force, --restart | Override single-instance behavior. |
--errorstdout[=ENC] | Write load-time errors to standard error, optionally using the specified encoding. |
--cpN | Read source files using code page N. |
--include <file> | Include a file before the main script. |
--debug | Reserved for compatibility with the AutoHotkey debugging-client switch; it does not start a Keysharp debugger. |
--iLib <ignored> | Deprecated alias for --validate. |
--validate | Parse and compile the source without running it. |
--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. |
--compile exe | Build a standalone executable which still requires .NET 10. |
--compile exe-min | Build an executable with dependencies embedded in the generated DLL. 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. |
--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.
Use Keysharp.exe --help to confirm the options supported by the installed build.
Keysharp.exe --compile exe hello.ks
Compilation first parses and lowers the Keysharp script to C#, then compiles it with Roslyn. Use --validate for a quick syntax and compilation check, or --transpile when diagnosing generated-code behavior.
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. The available presentation is platform-dependent. 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 and Exit. Help 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, KeyHistory and ListLines select related views; ListLines itself does not provide interpreter line history.
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. The bundled WindowSpy.cks is preferred when present, with WindowSpy.ks used as a fallback.
On Linux, Accessibility Spy launches AtSpi.ks. On macOS it launches Ax.ks. These inspectors expose platform accessibility information which is not represented by Windows ClassNN values.
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.
Compatibility note: Much of this reference originated in AutoHotkeyDocs. A described function may be part of the language target before its Keysharp implementation is complete. Reproducible gaps should be reported to the Keysharp issue tracker.