⇐ KbdEmu Docs

# Usage

This page assumes you have already installed KbdEmu. If not, follow the installation instructions on the installation page:

Installation

## Scripts#

KbdEmu uses scpt as its scripting language. The example script for kbdemu looks like this:

    set testKey to "x"
    keystroke $testKey with action "hold"
    sleep "1s"
    keystroke $testKey with action "release"
    type "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz"
    scroll 5 with direction "up"
    click "right"
    move-mouse [0, 0]
    send-notification "Test"
    beep
    open-location "https://www.arsenm.dev/"
    set showDetails to (display-dialog "Show details?" with type "yesno")
    if $showDetails {
      display-dialog {"Color: " + (pixel-color [100, 100]) + ", Mouse: " + (str (mouse-position))} with title "Details"
    }
    print {"\n" + (user-choice "test" with items ["Hello", "World", 3.1415926535, $GOOS, $GOARCH, true, false, (numcpu)])}
    log "Complete!"

By default, the `kbdemu` command will look for and execute a file called `kbdemu.scpt`, but that can be changed using the `--file` flag.

## Builtins#

KbdEmu comes with some extra functions for automation

### `numcpu` #

Returns the amount of available CPUs as a number.

Example:

    print (numcpu)

### `sleep` #

Sleeps for a duration as specified by an unnamed string argument formatted according to the specification of golang’s `time.ParseDuration()`:

Godoc

Examples:

    sleep "1s"
    sleep "1h2m"

### `display-dialog` #

Displays a dialog window with the specified parameters.

Examples:

    display-dialog "Test1"
    display-dialog "Test2" with title "Title Test"
    print (display-dialog "Test3" with title "Entry Test" with type "entry")

These are all the supported dialog types:

- info
- warning
- error
- entry
- yesno

Default dialog type is info.

### `send-notification` #

Sends a notification according to the specified parameters

Examples:

    send-notification "Test"
    send-notification "Test" with title "Title"
    send-notification "Test" with title "Title" with icon "test.png"

### `beep` #

Creates a beep sound, if impossible, falls back to sending bell character.

Examples:

    beep
    beep "3s"

### `click` #

Emulates a mouse click

Example:

    click "right"

### `scroll` #

Scrolls the specifed amount in the specified direction

Example:

    scroll 5 with direction "up"

### `move-mouse` #

Moves the cursor to the specified coordinates

Example:

    move-mouse [100, 200]

### `keystroke` #

Emulates a key event

Examples:

    keystroke "y" with action "hold"
    sleep "2s"
    keystroke "y" with action "release"
    keystroke "x"

Default action is `tap` which presses and releases the key.

### `type` #

Types a string using the keyboard

Example:

    type "Hello, World"

### `mouse-position` #

Returns the current mouse position in the form of an array containing two number elements.

Example:

    print (mouse-position) # [0 0]

### `pixel-color` #

Returns a string containing the hex color of the given coordinates.

Example:

    print (pixel-color [100, 100]) # ffffff

### `log` #

Logs the provided message at the given level.

Examples:

    log "Complete"
    log "Error" with level "fatal"

The available levels are:

- info
- debug
- warn
- fatal

Default log level is info

### `user-choice` #

Displays a user choice dialog window with provided items, returns selected item.

Example:

    user-choice "Choose an option" with items ["Hello", "World", 1, 3.14159, 6.28318]

### `open-location` #

Opens given URL in the default application set to open it.

Examples:

    open-location "https://www.arsenm.dev"
    open-location "/home"

## Variables#

KbdEmu exposes some variables for use in scripts.

### `$GOOS` #

The value from golang’s `runtime.GOOS`

Godoc

### `$GOARCH` #

The value from golang’s `runtime.GOARCH`

Godoc

### `$arguments` #

Non-flag command line arguments provided to KbdEmu

Example:

Command:

    kbdemu --file script.scpt "Hello, World"

Contents of `script.scpt`:

    print $arguments[0] # Hello, World