Skip to main content

Crate alfred_workflow_rs

Crate alfred_workflow_rs 

Source
Expand description

Strict Rust port of the Dart alfred_workflow package.

The crate is library-first and focuses on Alfred Script Filter JSON, workflow output, file caching, plist user defaults, and GitHub updater behavior with Dart-compatible wire formats.

use alfred_workflow_rs::{Item, Result, Workflow};

let mut workflow = Workflow::new();
workflow.add_item(Item::with_arg("Search Google", "https://www.google.com"))?;

assert_eq!(
    workflow.to_json_string()?,
    r#"{"items":[{"title":"Search Google","type":"default","valid":false,"arg":"https://www.google.com"}]}"#
);

§alfred_workflow_rs

CI crates.io Crates.io MSRV Crates.io Total Downloads docs.rs codecov Codacy Badge GitHub License

Build Alfred workflows in Rust with Script Filter output, file caching, plist user configuration, and GitHub release updates. This crate is a Rust port of the Dart alfred_workflow package.

§Install

[dependencies]
alfred_workflow_rs = "1.0.2"

The crate requires Rust 1.92 or newer.

§Basic Usage

use alfred_workflow_rs::{Item, Result, Workflow};

fn main() -> Result<()> {
    let mut workflow = Workflow::new();
    workflow.add_item(
        Item::with_arg("Search Google", "https://www.google.com/search?q=alfred")
            .set_subtitle("Open search results")
            .set_valid(true),
    )?;

    workflow.write_stdout()
}

§Cache Usage

use alfred_workflow_rs::{FileCache, Item, Items, Result, Workflow};

fn main() -> Result<()> {
    let mut workflow = Workflow::with_file_cache(FileCache::<Items>::new());
    workflow.set_cache_key(Some("query"));

    if workflow.get_items()?.is_empty() {
        workflow.add_item(Item::with_arg("Result", "result-arg"))?;
    }

    workflow.write_stdout()
}

§User Configuration

use alfred_workflow_rs::{Result, Workflow};

fn main() -> Result<()> {
    let workflow = Workflow::new();
    let defaults = workflow.get_user_defaults("info.plist", "prefs.plist")?;

    for (variable, config) in defaults {
        println!("{variable}: {}", config.configuration_type().as_str());
    }

    Ok(())
}

§Updater

use std::time::Duration;

use alfred_workflow_rs::{Result, Updater};

fn main() -> Result<()> {
    let updater = Updater::builder("https://github.com/owner/workflow".parse()?, "1.0.0")?
        .update_interval(Duration::from_secs(7 * 24 * 60 * 60))
        .build()?;

    if updater.update_available()? {
        updater.update()?;
    }

    Ok(())
}

§Examples

The Rust examples mirror the Dart package examples and compile with cargo test --examples:

Run one with:

cargo run --example basic -- --query "hello"

§Compatibility Notes

  • Alfred Script Filter JSON preserves Dart and Alfred wire keys such as quicklookurl, largetype, skipknowledge, and loosereload.
  • Items::exact_order(true) removes item uid values from serialized output.
  • Missing plist files return empty maps in Rust.
  • APIs are blocking by default; there is no async feature in the release path.
  • The updater opens downloaded .alfredworkflow files through an injectable opener. Tests never invoke the macOS open command.
  • The crate is macOS-oriented because Alfred is macOS-only, but the model and serialization tests are ordinary Rust tests.

§Development Checks

make ci
cargo test --examples --locked
make package-test

Published API documentation is available on docs.rs and GitHub Pages.

Re-exports§

pub use action::Action;
pub use action::ActionText;
pub use action::TypedAction;
pub use automatic_cache::AutomaticCache;
pub use cache::FileCache;
pub use cache::FileCacheBuilder;
pub use cache::WorkflowCache;
pub use error::Error;
pub use error::Result;
pub use item::Icon;
pub use item::IconType;
pub use item::Item;
pub use item::ItemBuilder;
pub use item::ItemText;
pub use item::ItemType;
pub use item::Modifier;
pub use item::ModifierKey;
pub use items::Items;
pub use updater::CommandOpener;
pub use updater::GithubAsset;
pub use updater::GithubRelease;
pub use updater::GithubUser;
pub use updater::Opener;
pub use updater::Updater;
pub use updater::UpdaterBuilder;
pub use updater::parse_version_tag;
pub use user_config::CheckBoxConfiguration;
pub use user_config::CheckBoxUserConfiguration;
pub use user_config::FilePickerConfiguration;
pub use user_config::FilePickerUserConfiguration;
pub use user_config::NumberSliderConfiguration;
pub use user_config::NumberSliderUserConfiguration;
pub use user_config::SelectConfiguration;
pub use user_config::SelectPair;
pub use user_config::SelectUserConfiguration;
pub use user_config::TextAreaConfiguration;
pub use user_config::TextAreaUserConfiguration;
pub use user_config::TextFieldConfiguration;
pub use user_config::TextFieldUserConfiguration;
pub use user_config::UserConfiguration;
pub use user_config::UserConfigurationType;
pub use user_config::UserPreferences;
pub use workflow::RenderOptions;
pub use workflow::Workflow;
pub use workflow::WorkflowBuilder;

Modules§

action
Alfred action model types.
automatic_cache
Automatic Script Filter cache metadata.
cache
File-backed workflow cache types.
error
Crate error and result types.
item
Alfred Script Filter item model types.
items
Alfred Script Filter result collection model.
updater
GitHub release updater support.
user_config
Alfred user configuration plist parsing.
workflow
In-memory workflow builder and renderer.