Vial CLI tool

Vial CLI tool allows to configure keyboard through VIA/Vial protocol with command line interface. It supports QMK keycodes notation together with aliases.

Keys, encoders, combos, macros, tap dances, key overrides and alt repeat keys are supported. RGB lighting control is supported too.

Non-colored underglow is not supported for now because there is no devices with such features around me.

Tool support --help for tool as a whole and for all subcommands.

Installation

vitaly might be installed with cargo on macosx, linux and windows

cargo install vitaly

On linux you'll need to install libudev-dev depending on your linux dist something like

sudo apt install libudev-dev

On macosx and linux you can also use homebew to install vitaly with command

brew install bskaplou/tap/vitaly

Prebuilt binary and installation instructions for Windows, MacOSX, Linux are here https://github.com/bskaplou/vitaly/releases/latest

Development

Just edit files and run following command to run tool in debug mode

cargo run -- <your_options>

Global options

Identifier

By default tool runs subcommands on all connected devices.

Option --id/-i can be used to select particular device.

For example

❯ vitaly devices # all devices
Product name: "Keychron K6 Pro" id: 611,
Manufacturer name: "Keychron", id: 13364,
Release: 256, Serial: "", Path: "DevSrvsID:4294971185"

Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4296802461"


❯ vitaly -i 611 devices # single device
Product name: "Keychron K6 Pro" id: 611,
Manufacturer name: "Keychron", id: 13364,
Release: 256, Serial: "", Path: "DevSrvsID:4294971185"

Devices subcommand

Devices subcommand allows to list compatible devices. For example

❯ vitaly devices
Product name: "Keychron K6 Pro" id: 611,
Manufacturer name: "Keychron", id: 13364,
Release: 256, Serial: "", Path: "DevSrvsID:4294971185"

Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4296802461"

Flag -c allows to list devices capabilities as well. For example

❯ vitaly devices -c
Product name: "Keychron K6 Pro" id: 611,
Manufacturer name: "Keychron", id: 13364,
Release: 256, Serial: "", Path: "DevSrvsID:4294971185"
Capabilities:
    via_version: 12
    vial_version: 0
    companion_hid_version: 1
    layer_count: 5
    tap_dance_count: 0
    combo_count: 0
    key_override_count: 0
    alt_repeat_key_count: 0
    caps_word: false
    layer_lock: false

Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4296802461"
Capabilities:
    via_version: 9
    vial_version: 6
    companion_hid_version: 1
    layer_count: 8
    tap_dance_count: 32
    combo_count: 32
    key_override_count: 32
    alt_repeat_key_count: 32
    caps_word: true
    layer_lock: true

Lock subcommand

Lock subcommand allows to check lock status and to lock/unlock keyboard.

❯ vitaly lock
Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4316856206"
Device is locked: true

To unlock keyboard run it with -u option and follow instructions

❯ vitaly lock -u
Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4316856206"
Device is locked: true
Starting unlock process...
Push marked buttons and keep then pushed to unlock...
...
Seconds remaining: 0 keep pushing...
Device is locked: false

To lock keyboard run it with -l option

❯ vitaly lock -l
Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4316856206"
Locking keyboard...
Device is locked: true

Settings subcommand

Settings subcommand allows to list and alter keyboard settings.

Settings in list are addressed by qsid - QMK setting identifier and with bit for boolean settings encoded into bits.

It allows to dump full list of settings together with current values as follows

❯ vitaly -i 4626 settings
Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4296802461"

Magic:
    21.0) Swap Caps Lock and Left Control = false
    21.1) Treat Caps Lock as Control = false
    21.2) Swap Left Alt and GUI = false
    21.3) Swap Right Alt and GUI = false
    21.4) Disable the GUI keys = false
    21.5) Swap ` and Escape = false
    21.6) Swap \ and Backspace = false
    21.7) Enable N-key rollover = false
    21.8) Swap Left Control and GUI = false
    21.9) Swap Right Control and GUI = false

Grave Escape:
    1.0) Always send Escape if Alt is pressed = false
    1.1) Always send Escape if Control is pressed = false
    1.2) Always send Escape if GUI is pressed = false
    1.3) Always send Escape if Shift is pressed = false

Tap-Hold:
    7) Tapping Term = 200
    22) Permissive Hold = false
    23) Hold On Other Key Press = false
    24) Retro Tapping = false
    25) Quick Tap Term = 200
    18) Tap Code Delay = 0
    19) Tap Hold Caps Delay = 80
    20) Tapping Toggle = 5
    26) Chordal Hold = false
    27) Flow Tap = 0

Auto Shift:
    3.0) Enable = false
    3.1) Enable for modifiers = false
    4) Timeout = 175
    3.2) Do not Auto Shift special keys = false
    3.3) Do not Auto Shift numeric keys = false
    3.4) Do not Auto Shift alpha characters = false
    3.5) Enable keyrepeat = false
    3.6) Disable keyrepeat when timeout is exceeded = false

Combo:
    2) Time out period for combos = 30

One Shot Keys:
    5) Tapping this number of times holds the key until tapped once again = 5
    6) Time (in ms) before the one shot key is released = 5000

Mouse keys:
    9) Delay between pressing a movement key and cursor movement = 10
    10) Time between cursor movements in milliseconds = 20
    11) Step size = 8
    12) Maximum cursor speed at which acceleration stops = 10
    13) Time until maximum cursor speed is reached = 30
    14) Delay between pressing a wheel key and wheel movement = 10
    15) Time between wheel movements = 80
    16) Maximum number of scroll steps per scroll action = 8
    17) Time until maximum scroll speed is reached = 40

It also allows to dump single setting if called with option --qsid/-q as follows

❯ vitaly -i 4626 settings --qsid 6
Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4296802461"
6) Time (in ms) before the one shot key is released = 5000

It allows to alter setting if called with options -q and -v while -q addresses setting to be altered and -v passess desired value as follows

❯ vitaly -i 4626 settings --qsid 6 -v 4000
Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4316856206"
Option "Time (in ms) before the one shot key is released" = 4000 now

Boolean option example

❯ vitaly -i 4626 settings -q 26
Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4316856206"
26) Chordal Hold = false

Boolean option encoded into bit

❯ vitaly -i 4626 settings -q 3.2 -v true
Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4316856206"
Option "Do not Auto Shift special keys" = true now

❯ vitaly -i 4626 settings -q 3.2
Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4316856206"
3.2) Do not Auto Shift special keys = true

It also allows to reset all settings to default values if called with option --reset/-r.

Layers subcommand

Layers subcommand is designed to help with visual layers dumping

It can dump button wiring positings if called with option positions

❯ vitaly -i 4626 layers -p
Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4316856206"
        ╔══╗╔══╗                     ╔══╗╔══╗
╔══╗╔══╗║0 ║║0 ║╔══╗             ╔══╗║5 ║║5 ║╔══╗╔══╗
║0 ║║0 ║║2 ║║3 ║║0 ║╔══╗     ╔══╗║5 ║║3 ║║2 ║║5 ║║5 ║
║0 ║║1 ║╚══╝╚══╝║4 ║║0 ║     ║5 ║║4 ║╚══╝╚══╝║1 ║║0 ║
╚══╝╚══╝╔══╗╔══╗╚══╝║5 ║     ║5 ║╚══╝╔══╗╔══╗╚══╝╚══╝
╔══╗╔══╗║1 ║║1 ║╔══╗╚══╝     ╚══╝╔══╗║6 ║║6 ║╔══╗╔══╗
║1 ║║1 ║║2 ║║3 ║║1 ║╔══╗     ╔══╗║6 ║║3 ║║2 ║║6 ║║6 ║
║0 ║║1 ║╚══╝╚══╝║4 ║║1 ║     ║6 ║║4 ║╚══╝╚══╝║1 ║║0 ║
╚══╝╚══╝╔══╗╔══╗╚══╝║5 ║     ║5 ║╚══╝╔══╗╔══╗╚══╝╚══╝
╔══╗╔══╗║2 ║║2 ║╔══╗╚══╝     ╚══╝╔══╗║7 ║║7 ║╔══╗╔══╗
║2 ║║2 ║║2 ║║3 ║║2 ║╔══╗     ╔══╗║7 ║║3 ║║2 ║║7 ║║7 ║
║0 ║║1 ║╚══╝╚══╝║4 ║║2 ║     ║7 ║║4 ║╚══╝╚══╝║1 ║║0 ║
╚══╝╚══╝╔══╗╔══╗╚══╝║5 ║     ║5 ║╚══╝╔══╗╔══╗╚══╝╚══╝
╔══╗╔══╗║3 ║║3 ║╔══╗╚══╝     ╚══╝╔══╗║8 ║║8 ║╔══╗╔══╗
║3 ║║3 ║║2 ║║3 ║║3 ║╔══╗     ╔══╗║8 ║║3 ║║2 ║║8 ║║8 ║
║0 ║║1 ║╚══╝╚══╝║4 ║║3 ║     ║8 ║║4 ║╚══╝╚══╝║1 ║║0 ║
╚══╝╚══╝        ╚══╝║5 ║     ║5 ║╚══╝        ╚══╝╚══╝
                    ╚══╝     ╚══╝

           ╔══╗╔══╗ ╔══╗     ╔══╗ ╔══╗╔══╗
           ║4 ║║4 ║ ║4 ║     ║9 ║ ║9 ║║9 ║
           ║3 ║║4 ║ ║5 ║     ║5 ║ ║4 ║║3 ║
           ╚══╝╚══╝ ╚══╝     ╚══╝ ╚══╝╚══╝

It also can dump current layer keymap

❯ vitaly -i 4626 layers
Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4316856206"
Layer: 0
        ╔══╗╔══╗                     ╔══╗╔══╗
╔══╗╔══╗║2 ║║3 ║╔══╗             ╔══╗║8 ║║9 ║╔══╗╔══╗
║⎋ ║║1 ║║  ║║  ║║4 ║╔══╗     ╔══╗║7 ║║  ║║  ║║0 ║║- ║
║  ║║  ║╚══╝╚══╝║  ║║5 ║     ║6 ║║  ║╚══╝╚══╝║  ║║  ║
╚══╝╚══╝╔══╗╔══╗╚══╝║  ║     ║  ║╚══╝╔══╗╔══╗╚══╝╚══╝
╔══╗╔══╗║W ║║E ║╔══╗╚══╝     ╚══╝╔══╗║I ║║O ║╔══╗╔══╗
║⇥ ║║Q ║║  ║║  ║║R ║╔══╗     ╔══╗║U ║║  ║║  ║║P ║║= ║
║  ║║  ║╚══╝╚══╝║  ║║T ║     ║Y ║║  ║╚══╝╚══╝║  ║║  ║
╚══╝╚══╝╔══╗╔══╗╚══╝║  ║     ║  ║╚══╝╔══╗╔══╗╚══╝╚══╝
╔══╗╔══╗║S ║║D ║╔══╗╚══╝     ╚══╝╔══╗║K ║║L ║╔══╗╔══╗
║MO║║A ║║  ║║  ║║F ║╔══╗     ╔══╗║J ║║  ║║  ║║; ║║' ║
║1 ║║  ║╚══╝╚══╝║  ║║G ║     ║H ║║  ║╚══╝╚══╝║  ║║  ║
╚══╝╚══╝╔══╗╔══╗╚══╝║  ║     ║  ║╚══╝╔══╗╔══╗╚══╝╚══╝
╔══╗╔══╗║X ║║C ║╔══╗╚══╝     ╚══╝╔══╗║, ║║. ║╔══╗╔══╗
║L⇧║║Z ║║  ║║  ║║V ║╔══╗     ╔══╗║M ║║  ║║  ║║/ ║║R⇧║
║  ║║  ║╚══╝╚══╝║  ║║B ║     ║N ║║  ║╚══╝╚══╝║  ║║  ║
╚══╝╚══╝        ╚══╝║  ║     ║  ║╚══╝        ╚══╝╚══╝
                    ╚══╝     ╚══╝

           ╔══╗╔══╗ ╔══╗     ╔══╗ ╔══╗╔══╗
           ║L⎈║║L⌥║ ║L⌘║     ║␣ ║ ║⏎ ║║R⌘║
           ║  ║║  ║ ║  ║     ║  ║ ║  ║║  ║
           ╚══╝╚══╝ ╚══╝     ╚══╝ ╚══╝╚══╝

Layer command accepts --number option which specifies layer number to dump

❯ vitaly -i 4626 layers -n 2
Product name: "silakka54" id: 4626,
Manufacturer name: "Squalius-cephalus", id: 65261,
Release: 256, Serial: "vial:f64c2b3c", Path: "DevSrvsID:4316856206"
Layer: 2
        ╔══╗╔══╗                     ╔══╗╔══╗
╔══╗╔══╗║▽ ║║▽ ║╔══╗             ╔══╗║▽ ║║▽ ║╔══╗╔══╗
║▽ ║║▽ ║║  ║║  ║║▽ ║╔══╗     ╔══╗║▽ ║║  ║║  ║║▽ ║║▽ ║
║  ║║  ║╚══╝╚══╝║  ║║▽ ║     ║▽ ║║  ║╚══╝╚══╝║  ║║  ║
╚══╝╚══╝╔══╗╔══╗╚══╝║  ║     ║  ║╚══╝╔══╗╔══╗╚══╝╚══╝
╔══╗╔══╗║▽ ║║▽ ║╔══╗╚══╝     ╚══╝╔══╗║Mo║║⚙↓║╔══╗╔══╗
║▽ ║║▽ ║║  ║║  ║║▽ ║╔══╗     ╔══╗║⚙↑║║↑ ║║  ║║▽ ║║▽ ║
║  ║║  ║╚══╝╚══╝║  ║║▽ ║     ║▽ ║║  ║╚══╝╚══╝║  ║║  ║
╚══╝╚══╝╔══╗╔══╗╚══╝║  ║     ║  ║╚══╝╔══╗╔══╗╚══╝╚══╝
╔══╗╔══╗║▽ ║║▽ ║╔══╗╚══╝     ╚══╝╔══╗║Mo║║Mo║╔══╗╔══╗
║▽ ║║▽ ║║  ║║  ║║▽ ║╔══╗     ╔══╗║Mo║║↓ ║║→ ║║⚙→║║▽ ║
║  ║║  ║╚══╝╚══╝║  ║║▽ ║     ║⚙←║║← ║╚══╝╚══╝║  ║║  ║
╚══╝╚══╝╔══╗╔══╗╚══╝║  ║     ║  ║╚══╝╔══╗╔══╗╚══╝╚══╝
╔══╗╔══╗║▽ ║║▽ ║╔══╗╚══╝     ╚══╝╔══╗║Mo║║▽ ║╔══╗╔══╗
║▽ ║║▽ ║║  ║║  ║║▽ ║╔══╗     ╔══╗║Mo║║5 ║║  ║║▽ ║║▽ ║
║  ║║  ║╚══╝╚══╝║  ║║▽ ║     ║Mo║║4 ║╚══╝╚══╝║  ║║  ║
╚══╝╚══╝        ╚══╝║  ║     ║3 ║╚══╝        ╚══╝╚══╝
                    ╚══╝     ╚══╝

           ╔══╗╔══╗ ╔══╗     ╔══╗ ╔══╗╔══╗
           ║▽ ║║▽ ║ ║▽ ║     ║Mo║ ║Mo║║*1║
           ║  ║║  ║ ║  ║     ║1 ║ ║2 ║║  ║
           ╚══╝╚══╝ ╚══╝     ╚══╝ ╚══╝╚══╝
*1 - QK_LAYER_LOCK

Flag --options/-o allows to override layout options for the dump. Format is group,variant;group,variant.

For keyboards with vial protocol support vitaly downloads vial.json file straight from the keyboard. For via-only keyboards vitaly will try to download keyboard specification from https://github.com/the-via/keyboards/tree/master/src. If specification of via-only keyboard not published on the-via/keyboards or it doesn't match your firmware repository specification file can be passed with -m option.

``` ❯ vitaly -i 611 layers -m k6pro.json Product name: "Keychron K6 Pro" id: 611, Manufacturer name: "Keychron", id: 13364, Release: 256, Serial: "", Path: "DevSrvsID:4316856485" Layer: 0 ╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══════╗╔══╗ ║⎋ ║║1 ║║2 ║║3 ║║4 ║║5 ║║6 ║║7 ║║8 ║║9 ║║0 ║║- ║║= ║║⌫ ║║*1║ ║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║ ╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══════╝╚══╝ ╔════╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔════╗╔══╗ ║⇥ ║║Q ║║W ║║E ║║R ║║T ║║Y ║║U ║║I ║║O ║║P ║║( ║║) ║║\ ║║⇱ ║ ║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║ ╚════╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚════╝╚══╝ ╔═════╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔═══════╗╔══╗ ║⇪ ║║A ║║S ║║D ║║F ║║G ║║H ║║J ║║K ║║L ║║; ║║' ║║⏎ ║║⇞ ║ ║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║║ ║ ╚═════╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚═══════╝╚══╝ ╔═══════╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔══╗╔═