Skip to content

Updating

Jump to bottom
argenkiwi edited this page Aug 11, 2026 · 1 revision

Updating

This guide explains how to update keydo to the latest version.

Note

Updating replaces the binary in place. Your configuration files are never touched during an update — you can keep using the same .conf files you already have.

Step 1 — Stop the Running Daemon

Before replacing the binary, stop the keydo daemon so the file is not locked.

Linux

# systemd
sudo systemctl stop keydo

# runit
sudo sv stop keydo

macOS

launchctl stop keydo

Windows (elevated Command Prompt)

keydo stop

Step 2 — Pull the Latest Source

Navigate to your local clone of the repository and fetch the latest changes:

cd keydo
git pull origin main

If you want to update to a specific tagged release instead of the latest commit on main, check out that tag:

git fetch --tags
git checkout v0.3.3   # replace with the desired version

You can browse all available releases on the GitHub Releases page.

Step 3 — Rebuild and Install the Binary

Recompile and overwrite the installed binary:

cargo install --path . --force

The --force flag is required to overwrite the existing installation.

Linux — copy the updated binary to the system path

If you previously copied the binary to /usr/local/bin/, repeat that step:

sudo cp ~/.cargo/bin/keydo /usr/local/bin/

Step 4 — Restart the Daemon

Linux

# systemd
sudo systemctl start keydo

# runit
sudo sv start keydo

macOS

launchctl start keydo

Windows (elevated Command Prompt)

keydo start

Step 5 — Verify the Update

Confirm that the running daemon reflects the new version:

keydo --version

Reviewing the Changelog

Before or after updating, review what changed in the new release:

  • GitHub Releases: github.com/argenkiwi/keydo/releases — each release is auto-generated from commit history.
  • Git log: git log --oneline v0.3.2..v0.3.3 (replace tags with the versions you're moving between).

Configuration Migration

keydo uses the keyd configuration syntax, which is stable across releases. However, after a major version bump:

  1. Re-check the release notes for any deprecated or renamed directives.
  2. Run the config checker against your existing files: 
    keydo check /path/to/your/config.conf
  3. Reload the daemon once you're satisfied: 
    keydo reload

Troubleshooting

The daemon fails to start after an update

Run the daemon in the foreground to see error output directly:

# Linux / macOS
keydo daemon

# Windows (elevated Command Prompt)
keydo daemon

macOS — Accessibility permissions lost after update

If you rebuilt the binary, macOS may revoke its Accessibility access because the binary has changed. Re-add it:

System Settings → Privacy & Security → Accessibility

Remove the old entry (if present) and add the updated binary at ~/.cargo/bin/keydo.

Windows — Emergency recovery

If input locks up after an update, press and hold Backspace + Enter + Escape simultaneously to instantly terminate the daemon and restore default keyboard behaviour.

Clone this wiki locally