Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ jobs:
shell: pwsh
run: |
$ErrorActionPreference = 'Stop'
foreach ($file in Get-ChildItem scripts -Filter '*.ps1') {
foreach ($file in Get-ChildItem -Path scripts,src/update -Filter '*.ps1') {
$tokens = $null
$errors = $null
$null = [System.Management.Automation.Language.Parser]::ParseFile($file.FullName, [ref]$tokens, [ref]$errors)
Expand Down Expand Up @@ -141,8 +141,8 @@ jobs:
- name: Check shell scripts
if: matrix.os == 'ubuntu-latest'
run: |
for script in scripts/*.sh packaging/omarchy-bar/*.sh; do bash -n "$script"; done
shellcheck scripts/*.sh packaging/omarchy-bar/*.sh
for script in scripts/*.sh packaging/omarchy-bar/*.sh src/update/*.sh; do bash -n "$script"; done
shellcheck scripts/*.sh packaging/omarchy-bar/*.sh src/update/*.sh
- name: Check macOS menu bar helper
if: matrix.os == 'macos-latest' && needs.scope.outputs.native == 'true'
run: |
Expand Down
2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ evdev = "0.13"
maintainer = "Muneer Alam <muneer.alam320@gmail.com>"
copyright = "2026, Muneer Alam"
license-file = ["LICENSE", "0"]
depends = "$auto, systemd, udev"
depends = "$auto, systemd, udev, curl"
section = "sound"
priority = "optional"
extended-description = """\
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ Any ordinary keyboard works; the sound is added in software. Linux reads evdev b
<details>
<summary><strong>Does it record what I type?</strong></summary>

Normal operation stores no typed text, logs no key names and sends no network requests. Global keyboard permission is sensitive, so grant it only to trusted software. Unix benchmark mode prints mapped key names and is for controlled tests. [Privacy and security](SECURITY.md)
Normal playback stores no typed text, logs no key names and sends no network requests. Explicit update checks contact GitHub without sending keyboard events or settings. Global keyboard permission is sensitive, so grant it only to trusted software. Unix benchmark mode prints mapped key names and is for controlled tests. [Privacy and security](SECURITY.md)

</details>

Expand All @@ -187,6 +187,8 @@ The [troubleshooting guide](docs/TROUBLESHOOTING.md) covers permissions, startup

Use the method you installed with. Microsoft Store manages updates for its copy. For helper installations, rerun the install command above. For package managers, follow the [Homebrew](docs/INSTALLATION.md#homebrew) or [Scoop](docs/INSTALLATION.md#scoop) update steps, including stopping Klicky first. Settings and custom sounds are preserved during updates.

Current source also includes a [centralized update command](docs/INSTALLATION.md#centralized-update-command); it will reach packaged installations with the next app release.

</details>

<details>
Expand Down
4 changes: 3 additions & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,9 @@ The daemon receives raw global key-down events, including events generated while

### Network behavior

Klicky contains no network client and makes no network requests.
Keyboard playback makes no network requests. Update checks run only when requested with `klicky update` or the Windows tray's **Check for updates** action. The check uses HTTPS to read the latest stable release from GitHub; GitHub receives the request's IP address and a Klicky update-check user agent. No keyboard events, settings or usage statistics are included. There is no background update polling.

After confirmation, the existing installer or package manager handles downloads and installation. Store installations stay under Microsoft Store's control. Unknown, portable and source builds are not automatically overwritten. Windows standalone updates use the official HTTPS installation helper and its release checksum verification; this is not a code-signing or antivirus guarantee.

## Operational guidance

Expand Down
4 changes: 4 additions & 0 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

Klicky uses one resident process per user session. Linux/macOS retain their Unix daemon and service lifecycle; Windows has a native tray coordinator with separate input, audio and control adapters. Sound-pack preparation and mixer-facing types are shared. The library entrypoint selects the platform at compile time.

## Explicit updates

`src/update.rs` supplies both CLIs and the Windows tray with stable-release checks and installation-channel detection. Checks use a bounded HTTPS curl request only after an explicit action. Windows tray network work runs on the metadata worker, away from input, audio and GUI callbacks. Confirmed updates are handed to the installation owner; source and unknown copies receive manual guidance. The update command never becomes a second package manager.

## Data flow

```mermaid
Expand Down
23 changes: 23 additions & 0 deletions docs/INSTALLATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,29 @@

[Back to README](../README.md) · [Visual field guide](https://klicky.muneer320.tech/guide.html#installation) · [Troubleshooting](TROUBLESHOOTING.md)

## Centralized update command

The updater is included in current source and will ship in the next app release. For v0.6.1 and earlier, use the installation-specific update steps below.

```sh
klicky update --check
klicky update
```

`--check` shows the installed version, latest stable GitHub release and recognized installation method. It does not open an installer, stop playback or change files. Checks happen only when requested. GitHub receives a normal HTTPS request; no typing, settings or usage statistics are sent.

`klicky update` explains the update route and asks for confirmation. `--yes` accepts that handoff for terminal automation; it does not accept installer terms, bypass security or confirm completion. The Windows tray's **Check for updates** action uses the same check and offers the same handoff.

- **Microsoft Store:** opens Store's Downloads and updates page. Store controls which version is available.
- **Windows standalone installer:** opens an update terminal and the official installer wizard. Existing settings and custom packs remain.
- **Scoop (per-user):** opens a terminal, stops a running copy, refreshes Scoop and updates Klicky. A running/paused copy is restarted in its previous playback state; a stopped copy stays stopped.
- **Homebrew:** updates the tap and formula. A previously running engine and menu helper are restarted; the engine's paused state is restored. Login-startup preferences are not enabled by the updater.
- **APT:** refreshes repository metadata and upgrades the installed `klicky` package. It may request `sudo` approval.
- **pacman:** offers a full `pacman -Syu` system upgrade, rather than a partial upgrade. Review pacman's transaction before accepting it.
- **Source, portable, global Scoop or unknown copies:** shows manual guidance instead of guessing an installation method or replacing files.

Package-manager versions can arrive later than the GitHub release. A successful check is not proof that your manager already offers that version, and a Windows terminal handoff is not confirmation that installation completed. Use `klicky --version` in a new terminal afterward. The standalone Windows CLI currently requires its full path unless you have added it to PATH.

## Windows

**Windows 11 x64.** [Get Klicky from Microsoft Store](https://apps.microsoft.com/detail/9NLVFX7T2X6Q), then open it from Start. Use the tray menu to choose a pack, adjust volume, pause/resume or enable **Start with Windows**. The Store installs the complete app and manages updates.
Expand Down
8 changes: 8 additions & 0 deletions docs/klicky.1
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,14 @@ Klicky is a small daemon that plays mechanical keyboard sounds for global keypre
On Linux it reads keyboard events through evdev and works independently of Wayland or X11.
.SH COMMANDS
.TP
.B update [--check] [--yes]
Explicitly check the latest stable release and identify the installation method.
With --check, do not change files or open an update tool. Otherwise ask before
handing the update to its existing installer or package manager; --yes accepts
that handoff. Source, portable and unknown builds require manual updates.
The check contacts GitHub over HTTPS, without sending input or configuration.
There is no background polling.
.TP
.B start
Start the daemon in the foreground.
Startup is exclusive: another instance cannot take ownership while the daemon
Expand Down
2 changes: 1 addition & 1 deletion packaging/apt/guide.html
Original file line number Diff line number Diff line change
Expand Up @@ -728,7 +728,7 @@ <h2>Under the keycaps.</h2>
<h2>Local sounds. Sensitive permissions.</h2>
<p>
Normal operation does not store typed text, log key names, record
microphone audio or make network requests. Installation helpers
microphone audio or send keyboard events over the network. Explicit update checks contact GitHub without sending settings or input data. Installation helpers
download files; the running app needs no cloud service.
</p>
<p>
Expand Down
2 changes: 1 addition & 1 deletion packaging/apt/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -978,7 +978,7 @@ <h2 id="faq-title">Before you move in.</h2>
<details>
<summary>Does Klicky record what I type?</summary>
<p>
Normal operation does not store typed text, log key names or
Normal playback does not store typed text, log key names or
make network requests. It reads global keyboard events locally
to select sounds, so its input permission is sensitive. Unix
benchmark mode does print mapped key names; use it only for
Expand Down
4 changes: 2 additions & 2 deletions packaging/apt/privacy.html
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@
<p class="eyebrow">A little sound. A little clarity.</p>
<h1>Your typing stays on your device.</h1>
<p class="intro">Klicky plays keyboard sounds locally. There is no Klicky account, cloud service, advertising or analytics in the app.</p>
<p>Last updated: November 11, 2026. Maintained by <a href="https://muneer320.tech/">Muneer Alam</a> and the Klicky contributors.</p>
<p>Last updated: November 21, 2026. Maintained by <a href="https://muneer320.tech/">Muneer Alam</a> and the Klicky contributors.</p>
</div>
</div>
<main class="wrap docs-layout" id="main">
Expand All @@ -74,7 +74,7 @@ <h1>Your typing stays on your device.</h1>
<h2>What happens when you press a key?</h2>
<p>Klicky receives keyboard events so it can choose and play a sound while you use other apps. Normal playback does not record your typed text, save a history of keypresses or transmit those events. The Windows app does not access your microphone.</p>
<p>Global input access is sensitive: keyboard events can occur while you enter a password or other private information. Klicky does not need that text, but you should grant input access only to software you trust. On Windows, playback is paused while the desktop is locked or inactive.</p>
<p>The desktop app contains no network client and makes no network requests. It does not send your typing, sound choices or usage statistics to me or to another service.</p>
<p>Keyboard playback makes no network requests. If you request an update check, Klicky contacts GitHub over HTTPS to read its latest stable release. GitHub receives your IP address and a Klicky update-check user agent, but no typing, settings or usage statistics. There is no background polling. After confirmation, your existing installer or package manager handles downloads and installation.</p>
</section>
<section id="settings">
<h2>Settings and custom sounds stay local.</h2>
Expand Down
1 change: 1 addition & 0 deletions packaging/arch/.SRCINFO
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ pkgbase = klicky
makedepends = cargo
makedepends = git
depends = alsa-lib
depends = curl
depends = gcc-libs
depends = glibc
depends = systemd
Expand Down
2 changes: 1 addition & 1 deletion packaging/arch/PKGBUILD
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ pkgdesc="Low-latency mechanical keyboard sounds for Linux"
arch=('x86_64')
url="https://github.com/Muneer320/klicky"
license=('MIT')
depends=('alsa-lib' 'gcc-libs' 'glibc' 'systemd')
depends=('alsa-lib' 'curl' 'gcc-libs' 'glibc' 'systemd')
makedepends=('cargo' 'git')
options=('!debug')
source=("$pkgname::git+$url.git#tag=v$pkgver" 'check-stopped.sh' 'klicky-stopped.hook')
Expand Down
6 changes: 6 additions & 0 deletions scripts/install.ps1
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Downloads a published Windows installer; never uses expiring CI artifacts.
param([switch]$Update)

& {
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'
Expand Down Expand Up @@ -75,6 +77,10 @@
if (-not (Test-Path -LiteralPath $cli -PathType Leaf)) {
throw "Setup finished, but Klicky could not start because its control executable is missing: $cli. Details: $log`n$securityHelp`nIf there is no security detection, repair the installation with the official installer."
}
if ($Update) {
Write-Output 'Klicky update finished. The installer restored its previous running and pause state.'
return
}
$launch = Start-KlickyProcess -Stage 'Klicky startup after installation' -Options @{
FilePath = $cli; ArgumentList = @('service', 'start'); WindowStyle = 'Hidden'
}
Expand Down
10 changes: 10 additions & 0 deletions src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,15 @@ struct Cli {

#[derive(Subcommand)]
enum Commands {
/// Check for a stable release or open the supported update route
Update {
/// Only check; do not open an installer or package manager
#[arg(long)]
check: bool,
/// Accept the displayed update handoff without prompting
#[arg(long)]
yes: bool,
},
/// Start the klicky daemon
Start {
/// Print latency measurements for each keypress
Expand Down Expand Up @@ -76,6 +85,7 @@ pub fn run() -> Result<()> {
let cli = Cli::parse();

match cli.command {
Commands::Update { check, yes } => crate::update::run(check, yes)?,
Commands::Start { benchmark } => engine::run(benchmark)?,
Commands::Stop => service::stop()?,
Commands::List => cmd_list()?,
Expand Down
2 changes: 2 additions & 0 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ mod player;
#[cfg(any(target_os = "linux", target_os = "macos"))]
mod service;
mod soundpack;
#[cfg(any(target_os = "linux", target_os = "macos", target_os = "windows"))]
pub mod update;
#[cfg(target_os = "windows")]
pub mod windows;

Expand Down
Loading
Loading