feat: add CLI parameters for linux by retspen · Pull Request #792 · cjpais/Handy

retspen · 2026-02-11T18:05:44Z

Add CLI parameters using clap for better integration with Linux desktop environments, window managers, and autostart configurations
Extract toggle_transcription() into a reusable function shared between the SIGUSR2 signal handler and the new --toggle-transcription CLI flag
Update README with detailed setup instructions for GNOME, KDE, Sway, i3, and Hyprland

Before Submitting This PR

Please confirm you have done the following:

I have searched existing issues and pull requests (including closed ones) to ensure this isn't a duplicate
I have read CONTRIBUTING.md

If this is a feature or change that was previously closed/rejected:

I have explained in the description below why this should be reconsidered
I have gathered community feedback (link to discussion below)

Human Written Description

Added CLI parameters for Linux because on Wayland compositors in-app global shortcuts don't work reliably, you need an external way to control the app. For example, you can set up a custom shortcut in GNOME (Settings > Keyboard > Custom Shortcuts) config with handy --toggle-transcription. This gives users a native, compositor-friendly way to trigger transcription without relying on in-app hotkey registration.

IMPORTANT: all parameters don't effected settings state

Related Issues/Discussions

Discussion: #147

Testing

Run app and than in console run the next command to start transcription:

$ handy --toggle-transcription

and the same command to stop transcription.

Screenshots/Videos (if applicable)

AI Assistance

No AI was used in this PR
AI was used (please describe below)

If AI was used:

Tools used: Claude + Opus 4.6
How extensively: Extensively

…le-transcription, --debug) Add command-line interface using clap for better Linux desktop integration: - --start-hidden: launch without showing the main window - --no-tray: launch without system tray icon (closing window quits app) - --toggle-transcription: toggle recording on/off on a running instance via tauri_plugin_single_instance - --debug: enable debug mode with Trace-level logging (runtime-only) Extract toggle_transcription() from signal_handle.rs into a reusable function shared between SIGUSR2 handler and CLI single-instance callback. Update CLAUDE.md and README.md with CLI documentation including setup instructions for GNOME, KDE Plasma, Sway/i3, and Hyprland. Co-Authored-By: Claude Opus 4.6 <[email protected]>

Copilot

Pull request overview

Adds a small CLI interface to the Tauri app (primarily for Linux/Wayland desktop integration) so users can start hidden, disable tray, toggle transcription on a running instance, and enable debug logging.

Changes:

Introduces CliArgs (clap) and parses CLI flags in the Tauri binary.
Applies CLI overrides at runtime (start hidden, no tray, debug) and adds a single-instance arg handler to toggle transcription.
Refactors SIGUSR2 transcription toggle logic into a reusable toggle_transcription() helper and documents CLI usage.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`src-tauri/src/signal_handle.rs`	Extracts transcription toggle logic into a reusable function used by SIGUSR2 and CLI.
`src-tauri/src/main.rs`	Parses CLI args before launching the Tauri app.
`src-tauri/src/lib.rs`	Threads parsed CLI args into `run()`, applies runtime overrides, and handles single-instance toggle requests.
`src-tauri/src/cli.rs`	Defines CLI flags via `clap` derive.
`src-tauri/Cargo.toml`	Adds `clap` dependency.
`src-tauri/Cargo.lock`	Updates lockfile for the new dependency.
`README.md`	Documents CLI parameters and Wayland shortcut setup guidance.
`CLAUDE.md`	Documents the CLI feature and implementation locations.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-11T18:14:17Z

src-tauri/src/lib.rs

+        .plugin(tauri_plugin_single_instance::init(|app, args, _cwd| {
+            if args.iter().any(|a| a == "--toggle-transcription") {
+                signal_handle::toggle_transcription(app, "CLI");
+            } else {
+                show_main_window(app);
+            }
        }))


The --toggle-transcription flag is parsed into CliArgs but is only acted on when received through tauri_plugin_single_instance args. If the first (only) instance is launched with --toggle-transcription (e.g., from a WM shortcut when Handy isn’t running), the flag currently has no effect and the app will just start normally. Consider handling cli_args.toggle_transcription during startup (e.g., in .setup after initialization) and either toggling immediately or exiting with a clear message/behavior.

Copilot · 2026-02-11T18:14:17Z

src-tauri/src/lib.rs

+
            // Show main window only if not starting hidden
-            if !settings.start_hidden {
+            // CLI --start-hidden flag overrides the setting


Comment says “CLI --start-hidden flag overrides the setting”, but the logic uses settings.start_hidden || cli_args.start_hidden, which can only force hidden=true and cannot override a stored start_hidden=true to show the window. Consider rewording the comment to match the actual behavior (e.g., “CLI flag forces start hidden”).

Suggested change

// CLI --start-hidden flag overrides the setting

// CLI --start-hidden flag can force starting hidden (in addition to the setting)

Copilot · 2026-02-11T18:14:17Z

src-tauri/src/signal_handle.rs

+            if should_start {
+                *is_currently_active = true;
+            }


toggle_transcription updates active_toggles only when starting (*is_currently_active = true) but never flips it back to false when stopping. This makes CLI/SIGUSR2 toggling behave differently from the main shortcut toggle path (which sets the state to should_start), and can cause repeated toggles during/after stop to keep calling stop instead of allowing start. Consider updating the state to should_start in both branches (or otherwise making this logic consistent with shortcut/handler.rs).

Suggested change

if should_start {

*is_currently_active = true;

}

// Keep the toggle state consistent with the desired action:

// true when we should start, false when we should stop.

*is_currently_active = should_start;

cjpais · 2026-02-12T00:31:22Z

I appreciate small on scoped changes. This will likely be pulled in.

cjpais · 2026-02-16T14:44:43Z

@retspen can you rebase this so it also captures the recent SIGUSR1 changes. I may pull this in.

Resolve conflicts by adopting TranscriptionCoordinator from main while preserving CLI parameters functionality. toggle_transcription() now uses TranscriptionCoordinator instead of the removed ShortcutToggleStates/ManagedToggleState. Added SIGUSR1 support and updated README with both CLI docs and signal table. Co-Authored-By: Claude Opus 4.6 <[email protected]>

retspen · 2026-02-16T14:57:51Z

@retspen can you rebase this so it also captures the recent SIGUSR1 changes. I may pull this in.

Done

cjpais · 2026-02-16T14:58:50Z

thanks and you can confirm works fine for both shortcuts?

retspen · 2026-02-16T15:14:07Z

Yes, both.

fist time

second time

Thank you!

cjpais · 2026-02-17T04:44:05Z

I tested this and it does work great on my machine (MacOS)

retspen and others added 2 commits February 11, 2026 14:47

Merge branch 'main' into feat/cli-parameters

ebf89d5

Copilot AI review requested due to automatic review settings February 11, 2026 18:05

retspen closed this Feb 11, 2026

Copilot started reviewing on behalf of retspen February 11, 2026 18:06 View session

Copilot AI reviewed Feb 11, 2026

View reviewed changes

retspen reopened this Feb 11, 2026

cjpais added 4 commits February 17, 2026 12:26

Merge branch 'main' into feat/cli-parameters

a65dd7f

add cancel and post processs

0a7c3ca

cleanup

55bd69a

format

8ae8876

docs

9ddb18d

cjpais merged commit 133c50c into cjpais:main Feb 17, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add CLI parameters for linux#792

feat: add CLI parameters for linux#792
cjpais merged 8 commits intocjpais:mainfrom
retspen:feat/cli-parameters

retspen commented Feb 11, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 11, 2026

Uh oh!

Copilot AI Feb 11, 2026

Uh oh!

Copilot AI Feb 11, 2026

Uh oh!

cjpais commented Feb 12, 2026 •

edited

Loading

Uh oh!

cjpais commented Feb 16, 2026

Uh oh!

retspen commented Feb 16, 2026

Uh oh!

cjpais commented Feb 16, 2026

Uh oh!

retspen commented Feb 16, 2026 •

edited

Loading

Uh oh!

cjpais commented Feb 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	// CLI --start-hidden flag overrides the setting
	// CLI --start-hidden flag can force starting hidden (in addition to the setting)

-            if should_start {
-                *is_currently_active = true;
-            }
+            // Keep the toggle state consistent with the desired action:
+            // true when we should start, false when we should stop.
+            *is_currently_active = should_start;

Uh oh!

Conversation

retspen commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Before Submitting This PR

Human Written Description

Related Issues/Discussions

Testing

Screenshots/Videos (if applicable)

AI Assistance

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

cjpais commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cjpais commented Feb 16, 2026

Uh oh!

retspen commented Feb 16, 2026

Uh oh!

cjpais commented Feb 16, 2026

Uh oh!

retspen commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cjpais commented Feb 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

retspen commented Feb 11, 2026 •

edited

Loading

cjpais commented Feb 12, 2026 •

edited

Loading

retspen commented Feb 16, 2026 •

edited

Loading