Readme
handsfreectl
handsfreectl is a CLI for the Handsfree speech-to-text daemon (handsfreed ). It allows you to start and stop transcription, check the daemon's status, and more. The goal of handsfreectl is to provide a simple way to interact with the handsfreed daemon from the command line, making it easy to integrate with scripts, keyboard shortcuts, or other tools in a Linux desktop environment.
Installation
handsfreectl requires the handsfreed daemon to be installed and running. Please follow the instructions to install handsfreed first.
There are several ways to install handsfreectl :
Pre-compiled Binaries
You can download pre-compiled binaries directly from the GitHub Releases page . This is a good option if you don't have Cargo installed. After downloading, make sure to place the binary in a directory that is included in your system's PATH environment variable.
From Crates.io
If you have the Cargo installed, you can install handsfreectl from Crates.io using cargo :
cargo install handsfreectl
Nix Flake
If you use the Nix package manager with flakes enabled, there is a Handsfree flake that provides the handsfreectl and handsfreed packages along with a Home Manager module to configure and manage the handsfreed daemon as a systemd service.
For detailed instructions on how to add the flake to your system and configure the service, please refer to the Handsfree flake readme .
Build From Source
You can build handsfreectl from source using Cargo.
Prerequisites:
Rust: Version 1.85.0 or newer.
Steps:
Clone the Repository:
git clone https://github.com/achyudh/handsfreectl.git
cd handsfreectl
Build:
cargo build -- release
Install:
Copy the compiled binary to a directory that is included in your system's PATH environment variable.
Usage
handsfreectl communicates with the handsfreed daemon, which must be running for these commands to work.
Start Transcription:
Tells the daemon to start listening for speech. The transcribed text can be output as simulated keyboard input or copied to the clipboard, depending on the daemon's configuration.
handsfreectl start -- output keyboard
handsfreectl start -- output clipboard
Stop Transcription:
Tells the daemon to stop the current listening session.
handsfreectl stop
Toggle Transcription:
Toggles the transcription state. If Idle , it starts listening. If Listening , it stops. This is ideal for binding to a single hotkey.
handsfreectl toggle
handsfreectl toggle -- output clipboard
Check Status:
Queries the daemon's current state once.
handsfreectl status
Watch Status:
Streams status updates in real-time. This is efficient for status bars (like Waybar or Polybar) as it avoids polling.
handsfreectl watch
Possible outputs include Idle , Listening , Processing , Error , or Inactive .
Shutdown Daemon:
Tells the handsfreed process to shut down cleanly.
handsfreectl shutdown
License
This project is licensed under the GNU General Public License v3.0.