Input and Output

/**
 * User input from Alfred. What the user wrote in the input box.
 * Automatically populated from process.argv[2]
 */
input: string;

import alfy from "alfy";

console.log(`User typed: ${alfy.input}`);
// If user typed "hello world", this outputs: "User typed: hello world"

// Use input for filtering or processing
if (alfy.input.startsWith("search ")) {
  const query = alfy.input.slice(7); // Remove "search " prefix
  // Process the query...
}

/**
 * Return output to Alfred in Script Filter format
 * @param items - Array of result items to display
 * @param options - Optional configuration for output behavior
 */
function output(items: ScriptFilterItem[], options?: OutputOptions): void;

interface ScriptFilterItem {
  /** Unique identifier for learning and sorting */
  uid?: string;
  /** Main title displayed in result row (required) */
  title: string;
  /** Subtitle displayed below title */
  subtitle?: string;
  /** Argument passed to connected output actions */
  arg?: string;
  /** Icon configuration for the result */
  icon?: IconElement | string;
  /** Whether the item is actionable (default: true) */
  valid?: boolean;
  /** Custom match string for Alfred's filtering */
  match?: string;
  /** Text for auto-completion */
  autocomplete?: string;
  /** Item type for file handling */
  type?: 'default' | 'file' | 'file:skipcheck';
  /** Modifier key configurations */
  mods?: Partial<Record<ModifierKey, ModifierKeyItem>>;
  /** Copy and large type text configuration */
  text?: TextElement;
  /** Quick Look URL */
  quicklookurl?: string;
  /** Workflow variables */
  variables?: Record<string, string>;
}

interface OutputOptions {
  /** Re-run interval in seconds (0.1 to 5.0) for automatic updates */
  rerunInterval?: number;
}

import alfy from "alfy";

// Basic output
alfy.output([
  {
    title: "Unicorn",
    subtitle: "A magical creature",
    arg: "unicorn"
  },
  {
    title: "Rainbow",
    subtitle: "Colorful arc in the sky",
    arg: "rainbow"
  }
]);

// Advanced output with icons and modifiers
alfy.output([
  {
    uid: "file-123",
    title: "Important Document",
    subtitle: "~/Documents/report.pdf",
    arg: "~/Documents/report.pdf",
    type: "file",
    icon: {
      type: "fileicon",
      path: "~/Documents/report.pdf"
    },
    text: {
      copy: "~/Documents/report.pdf",
      largetype: "Path: ~/Documents/report.pdf"
    },
    mods: {
      cmd: {
        title: "Open in Finder",
        subtitle: "Reveal file in Finder",
        arg: "finder:~/Documents/report.pdf"
      }
    }
  }
]);

// Output with auto-refresh for progress updates
alfy.output(
  [
    {
      title: "Downloading Unicorns…",
      subtitle: `${progress}%`,
      valid: false
    }
  ],
  {
    rerunInterval: 3 // Re-run every 3 seconds
  }
);

interface IconElement {
  /** Path to icon file */
  path?: string;
  /** Icon type for special handling */
  type?: 'fileicon' | 'filetype';
}

interface TextElement {
  /** Text copied with ⌘C */
  copy?: string;
  /** Text displayed with ⌘L (Large Type) */
  largetype?: string;
}

interface ModifierKeyItem {
  /** Whether the modified item is valid */
  valid?: boolean;
  /** Modified title */
  title?: string;
  /** Modified subtitle */
  subtitle?: string;
  /** Modified argument */
  arg?: string;
  /** Modified icon path */
  icon?: string;
  /** Modified variables */
  variables?: Record<string, string>;
}

type ModifierKey = 'fn' | 'ctrl' | 'opt' | 'cmd' | 'shift';

import alfy from "alfy";

alfy.output([
  {
    title: "Delete File",
    subtitle: "Move to trash",
    arg: "delete:file.txt",
    mods: {
      cmd: {
        title: "Delete Permanently",
        subtitle: "Skip trash and delete permanently",
        arg: "delete-permanent:file.txt"
      },
      shift: {
        title: "Show in Finder",
        subtitle: "Reveal file location",
        arg: "reveal:file.txt"
      }
    }
  }
]);