Auto Launch

Auto launch any application or executable at startup. Supports Windows, macOS (Launch Agent, AppleScript, or SMAppService), and Linux.

How does it work? See Teamwork/node-auto-launch for details.

If you find any bugs, welcome to PR or issue.

Usage

The parameters of AutoLaunch::new are different on each platform. See the function definition or the demo below for details.

AutoLaunchBuilder helps to eliminate the constructor difference on various platforms.

use auto_launch::*;

fn main() {
    let auto = AutoLaunchBuilder::new()
        .set_app_name("the-app")
        .set_app_path("/path/to/the-app")
        .set_macos_launch_mode(MacOSLaunchMode::LaunchAgent)
        .build()
        .unwrap();

    auto.enable().unwrap();
    auto.is_enabled().unwrap();

    auto.disable().unwrap();
    auto.is_enabled().unwrap();
}

Linux

Linux supports two ways to achieve auto launch:

• XDG Autostart: Uses .desktop files in ~/.config/autostart/ (default)
• systemd: Uses systemd user services in ~/.config/systemd/user/
  • Uses systemctl --user enable to enable the service.
  • Requires systemctl to be available in the environment.

use auto_launch::{AutoLaunch, LinuxLaunchMode};

fn main() {
    let app_name = "the-app";
    let app_path = "/path/to/the-app";
    
    // Use XDG Autostart (default method)
    let auto = AutoLaunch::new(app_name, app_path, LinuxLaunchMode::XdgAutostart, &[] as &[&str]);
    
    // Or use systemd user service
    // let auto = AutoLaunch::new(app_name, app_path, LinuxLaunchMode::Systemd, &[] as &[&str]);

    // enable the auto launch
    auto.enable().is_ok();
    auto.is_enabled().unwrap();

    // disable the auto launch
    auto.disable().is_ok();
    auto.is_enabled().unwrap();
}

macOS

macOS supports three ways to achieve auto launch:

• Launch Agent: Uses plist files in ~/Library/LaunchAgents/ (default)
• AppleScript: Uses AppleScript to add login items
• SMAppService: Uses the SMAppService API (macOS 13+)

Note:

• The app_path should be an absolute path and exists. Otherwise, it will cause an error when enable.
• In case using AppleScript, the app_name should be same as the basename of app_path, or it will be corrected automatically.
• In case using AppleScript, only --hidden and --minimized in args are valid, which means that hide the app on launch.
• In case using SMAppService, app_name and app_path can be empty strings because it registers the running app.

use auto_launch::{AutoLaunch, MacOSLaunchMode};

fn main() {
    let app_name = "the-app";
    let app_path = "/path/to/the-app.app";
    
    // Use Launch Agent (default method)
    let auto = AutoLaunch::new(app_name, app_path, MacOSLaunchMode::LaunchAgent, &[] as &[&str], &[] as &[&str], "");
    
    // Or use AppleScript
    // let auto = AutoLaunch::new(app_name, app_path, MacOSLaunchMode::AppleScript, &[] as &[&str], &[] as &[&str], "");
    
    // Or use SMAppService (macOS 13+)
    // let auto = AutoLaunch::new(app_name, app_path, MacOSLaunchMode::SMAppService, &[] as &[&str], &[] as &[&str], "");

    // enable the auto launch
    auto.enable().is_ok();
    auto.is_enabled().unwrap();

    // disable the auto launch
    auto.disable().is_ok();
    auto.is_enabled().unwrap();
}

Windows

On Windows, it will add registry entries under:

• \HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run (system)
• \HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Run (current user)
• \HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\StartupApproved\Run (Task Manager status)

It will also detect if startup is disabled inside Task Manager or the Windows settings UI, and can re-enable after being disabled in one of those.

Pass app_path as an unquoted executable path and each element of args as a literal argument. One surrounding pair of quotes on app_path is also accepted for compatibility with existing callers. The crate handles Windows command-line quoting, including spaces, empty arguments, quotes and backslashes. Arguments follow the standard Windows C runtime conventions used by Rust and C/C++ executables; custom command interpreters may use different rules. After upgrading, call enable() again to rewrite an existing startup entry with the corrected command line.

Enable behavior is controlled by WindowsEnableMode:

• Dynamic (default): try system-wide, fall back to current user on access denied
• CurrentUser: write to current user only
• System: write to system only (admin required)

use auto_launch::{AutoLaunch, WindowsEnableMode};

fn main() {
    let app_name = "the-app";
    let app_path = "C:\\path\\to\\the-app.exe";
    let auto = AutoLaunch::new(app_name, app_path, WindowsEnableMode::Dynamic, &[] as &[&str]);

    // enable the auto launch
    auto.enable().is_ok();
    auto.is_enabled().unwrap();

    // disable the auto launch
    auto.disable().is_ok();
    auto.is_enabled().unwrap();
}

Tests

On Linux and FreeBSD, cargo test --test xdg_exec uses GLib's gio launch to check that an XDG desktop entry starts the executable with its original arguments. Install the gio command before running this test. It uses a temporary home directory and removes its desktop entry afterwards.

On Windows, cargo test --test windows_exec reads back a temporary current-user Run entry and launches that exact command with CreateProcessW, checking the executable path and received arguments. It removes its registry values and temporary files afterwards. This tests command parsing, not a desktop login.

License

MIT License. See the License file for details.

Acknowledgement

The project is based on node-auto-launch.