# Command Line Usage

### Command Line flags

We have created a command line interface which allows you to send mouse and keyboard commands to your RelayKeys hardware.

To run it access

`relaykeys-cli.exe command:data`

or if running it in pure python

`python relaykeys-cli.py command:data`

and the non-verbose, non-windowed version

`python relaykeys-cli-win.py command:data`

Where 'command' and 'data' are provided below.

{% hint style="info" %}
Remember to change your application accordingly We regularly use the term for command line application '*relaykeys-cli*' in this documentation. Often though you will want to use the '**relaykeys-cli-win.exe**' application that will run a little quicker and has no printed output. Use this for your default call to relaykeys from other applications. If you want to see any errors use '*relaykeys-cli.exe*'
{% endhint %}

{% hint style="info" %}
If you are developing with the code You must make sure the server is running when you call the cli files. The [server (aka Daemon)](/products/relaykeys/developers/relaykeys-daemon.md) is the code that turns these commands into the correct AT syntax and access the com port
{% endhint %}

### Defining a Keymap -c

Keymap files are located in [**cli\_keymap**](https://github.com/AceCentre/RelayKeys/tree/master/cli_keymaps) folder. You can choose which keymap file the CLI is going to use in the cfg by assigning file name to keymap\_file variable (see [here](https://github.com/AceCentre/RelayKeys/blob/12d3eadca2cea53561a5a3979562aae8b4b6cd7c/relaykeys-example.cfg#L17))

By default the **us\_keymap.json** is loaded.\
\
To run relaykeys-cli with other keymap either change the cfg setting [or use the -c flag](/products/relaykeys/developers/relaykeys-cfg.md) on the cli application. E.g.

`relaykeys-cli.exe -c .\relaykeys-example.cfg type:@`

See more info on the format [here](/products/relaykeys/developers/relaykeys-cfg.md#introduction)

### Command: paste

This takes the pasteboard of the computer (i.e. when you copy some text) and pastes the resulting string to RelayKeys

i.e.

`relaykeys-cli.exe paste`

### Command: type:text

Types the string following the :. Note you will need to escape spaces etc

`relaykeys-cli.exe type:Hello\ World`

#### A special note about type/paste

You can send special characters, ones that are usually shifted, by sending the key and the shift modifier (see **keyevent** below). But for the type and paste commands we have some other characters that are hardcoded and it will do the conversion on the fly.

So for example, to send the @ symbol:

`relaykeys-cli.exe type:@`

All codes which are converted can be seen below. **NB: \t = Tab \r\n are line breaks\~**

### Command: keypress:KEY,MODIFIER

Sends the KEY and any modifier, For example:

`relaykeys-cli.exe keypress:A`

Will emulate pressing and releasing the letter `A`. What about a shift?

`relaykeys-cli.exe keypress:A,LSHIFT`

Will emulate pressing the A with Left Shift. i.e. Upper casing the A.

`relaykeys-cliexe keypress:RIGHTARROW,LSHIFT,LCTRL`

Will press the right arrow, left shit and left control (would select the next word in programs like word)

#### Modifiers

* Left Control/CTRL: `LCTRL`
* Left Shift : `LSHIFT`
* Left Alt/Alt: `LALT`
* (Left) Meta/Windows Key/Mac Key/Command Key: `LMETA` **Note: On Windows there is generally only one Windows key. So use LMETA to emulate pressing the Windows key**
* Right Control/CTRL:: `LCTRL`
* Right Shift : `RSHIFT`
* (Right) Meta/Windows Key/Mac Key/Command Key: `RMETA`

{% hint style="info" %}
If you are wanting to send two keys with a modifier - send the **key** - **then** **modifier**. E.g. `keypress:C,LCTRL` - not the other way round! 
{% endhint %}

{% hint style="warning" %}
If you are sending to iOS or a Mac - remember that they use the Command (LMETA) key - often where windows uses the CTRL key read [here](https://support.apple.com/en-us/HT201236) for more examples
{% endhint %}

We also have a limited number of **consumer keys - namely volume related (if you need others do** [**let us know**](https://github.com/AceCentre/RelayKeys/issues/26)**)**

* Volume Up: `VOLUP`
* Volume Down: `VOLDOWN`
* Mute: `MUTE`

So all the other keys are defined below. We will try and explain what these are when its ambiguous

<details>

<summary>Keys</summary>

* 0
* 1
* 2
* 3
* 4
* 5
* 6
* 7
* 8
* 9
* A
* B
* C
* D
* E
* F
* G
* H
* I
* J
* K
* L
* M
* N
* O
* P
* Q
* R
* S
* T
* U
* V
* W
* X
* Y
* Z
* BACKSPACE - Back Delete key
* ENTER - Return
* DELETE - Forward delete key
* TAB
* PAUSE
* ESCAPE
* SPACE
* QUOTE
* COMMA
* MINUS
* PERIOD
* SLASH
* SEMICOLON
* EQUALS
* LEFTBRACKET
* BACKSLASH
* RIGHTBRACKET
* BACKQUOTE
* KP0
* KP1
* KP2
* KP3
* KP4
* KP5
* KP6
* KP7
* KP8
* KP9
* KP\_PERIOD
* KP\_DIVIDE
* KP\_MULTIPLY
* KP\_MINUS
* KP\_PLUS
* KP\_ENTER
* KP\_EQUAL - Keypad =
* KP\_COMMA
* KP\_EQSIGN
* UP
* DOWN
* RIGHT
* LEFT
* INSERT
* HOME
* END
* PAGEUP
* PAGEDOWN
* F1
* F2
* F3
* F4
* F5
* F6
* F7
* F8
* F9
* F10
* F11
* F12
* NUMLOCK
* CAPSLOCK
* SCROLLOCK
* RIGHTARROW
* LEFTARROW
* DOWNARROW
* UPARROW
* APP
* LGUI - Keyboard Left GUI
* RGUI - Keyboard Right GUI
* CUSTOM\~ - Keyboard Non-US # and \~
* PRINTSCREEN
* POWER
* EXECUTE
* HELP
* MENU
* SELECT
* STOP
* AGAIN
* UNDO
* CUT
* COPY
* PASTE
* FIND
* MUTE
* VOLUP
* VOLDOWN
* LOCKING\_CAPSLOCK
* LOCKING\_NUMLOCK
* LOCKING\_SCROLLOCK
* ALTERASE
* ATTENTION
* CANCEL
* CLEAR
* PRIOR
* RETURN
* SEPARATOR
* OUT 0xA0
* OPER 0xA1

</details>

### Command: keyevent:KEY,MODIFIER,Up/Down

Emulates holding or releasing one key with a modifer. For example:

`relaykeys-cli.exe keyevent:A,LSHIFT,1`

Emulates pressing a `A` with `Shift` Down. To release:

`relaykeys-cli.exe keyevent:A,LSHIFT,0`

So a classic example is to emulate pressing the Alt key and Tab key. Commonly used to switch applications. To do this you would need to send two commands.

```
    relaykeys-cli-win.exe" keyevent:TAB,LALT,1
    relaykeys-cli-win.exe" keyevent:TAB,LALT,0
```

### Command: keyboard\_release

Releases any keys that may have been held down, e.g. a modifier \
Particularly useful if you need to type on one the receiving device with a different keyboard.&#x20;

### Command: mousemove:PixelsRight,PixelsDown

Sends the command to move the mouse x Pixels Right and x Pixels Down. To go in the other direction send negative numbers. Eg. To go Right by 10 and Down by 10

`relaykeys-cli.exe mousemove:10,10`

and Left by 10, Up by 10:

`relaykeys-cli.exe mousemove:-10,-10`

Straight up:

`relaykeys-cli.exe mousemove:0,-10`

Straight down:

`relaykeys-cli.exe mousemove:0,10`

Straight right:

`relaykeys-cli.exe mousemove:10,0`

Straight left:

`relaykeys-cli.exe mousemove:-10,0`

{% hint style="info" %}
Want a way of repeating a mousemove for a while?\
Run the application called **mouserepeat.exe** which uou will find in the RelayKeys install folder. Run it with `mouserepeat.exe -x 10 -y 10` - where that is your mouse direction to move it in. It will then repeat that until you quit the application. To do this run a powershell script:\
\
`Stop-Process -Name "mouserepeat"`
{% endhint %}

### Command: mousebutton:Button,Behaviour

Sends the Mouse button press. Mouse buttons available:

* L: Left
* R: Right
* M: Middle
* F: Scroll Forward
* B: Scroll Backward

Behaviours:

* click
* doubleclick

Note: If you don't provide a behaviour it will hold and release the button for 0 Seconds.

Send a doubleclick:

`relaykeys-cli.exe mousebutton:L,doubleclick`

Send a right click:

`relaykeys-cli.exe mousebutton:R,click`

**What about dragging?**

Activate Drag Start button

`relaykeys-cli mousebutton:L,press`

User moves mouse

`relaykeys-cli mousemove:x,y`

User moves mouse some more

`relaykeys-cli mousemove:x,y`

user activates Drag Stop button

`relaykeys-cli mousebutton:0`

### Command: delay: nms

Adds a delay. Particularly useful when writing a macro and you need to wait for something to happen on the client operating system.

`relaykeys-cli delay:1000`

Puts in a a delay of 1 second.

### Device Management Commands

#### Optional extra flags --notfiy --copy

On the following commands you can provide a `--notify` flag. If so your Operating System will return a system notification. Useful if you dont have access to view the command line. Or if you wish provide a `--copy` flag. This will return the results to your pasteboard for you to paste the data back. **Be careful with this. It will overwrite any copy/paste functions you may already have.**

`relaykeys-cli.exe ble_cmd:devname`

Returns the currently connected device

`relaykeys-cli.exe ble_cmd:devlist`

Gets a list of devices that the device has in memory

`relaykeys-cli.exe ble_cmd:devadd`

Put the device into a pairing state

`relaykeys-cli.exe ble_cmd:devreset`

Reset the entire stored devices (its like wiping the volatile memory)

`relaykeys-cli.exe ble_cmd:switch`

Switch the current connected device to the next one in RelayKeys memory

`relaykeys-cli.exe ble_cmd:switch:"Name" --notify`\
\
Switches BLE device by the name of a device.&#x20;

`relaykeys-cli.exe ble_cmd:devremove=DEVNAME`

Remove just one named device from the memory.

`relaykeys-cli.exe ble_cmd:reconnect`

Tells the daemon/server to try and reconnect to the serial port.

`relaykeys-cli.exe daemon:switch_mode`

Tells the daemon/server to try and switch between wired

`relaykeys-cli.exe daemon:get_mode`

Returns current mode

`relaykeys-cli.exe daemon:dongle_status`

Returns whether it is connected or not

`relaykeys-cli.exe ble_cmd:get_mode`&#x20;

Gets the current mode - wired or wireless

`relaykeys-cli.exe ble_cmd:switch_mode`

Switches mode from Wired -> Wireless and Wireless-> Wired.

### Command: -f file.txt (Macro)

Provide a macro file - where each line in a text file is a cli command. For example **ios\_open\_notes.txt** found in the *macros* directory of the installation folder (i.e at *C:\Program Files (x86)\Ace Centre\RelayKeys\maccros)*

`relaykeys-cli.exe -f ios_open_notes.txt`

or like this

`relaykeys-cli.exe -f Documents/open_ios_notes.txt`

where it reads the file from a file path.. or..\
\
`relaykeys-cli.exe -f ./open_ios_notes.txt`

where it reads the file in folder where current exe is run from\\

where ios\_open\_notes.txt is:

```
keypress:H,LMETA
keypress:SPACE,LMETA
type:notes
delay:500
keypress:ENTER
```

{% hint style="info" %}
Warning: There is no syntax checking of this document.
{% endhint %}

{% hint style="info" %}
Want to send a long string of mouse commands and want to record your movements for a script? Use the RelayKeys-QT app and use the record macro function!
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.acecentre.org.uk/products/relaykeys/using-relaykeys/relaykeys-cli.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.