Skip to content

Macros (Automating Actions)

Zenith Filer includes a "Macros" feature for automating the operations you perform most often. Macros are JavaScript under the hood, but you can build them without writing any code — wire parts (blocks) together in Macro Studio, or record your actual operations — so they are approachable even for first-time users. Creation and editing always happen in Macro Studio; the nav pane's "Macros" view is dedicated to listing and running saved macros.

Where to Find Macros

  • The "Macros" view in the nav pane: A permanent view alongside Favorites, Tree, and the others (its icon is a lightning bolt ⚡). It lists your saved macros — each entry shows its name, badges for any configured triggers, and a ▶ run button. Double-click to run, or right-click for Run / Edit in Studio / Duplicate / Delete. The "+" button in the header opens Macro Studio in a fresh, new-macro state.
  • The two icons on the right side of the status bar: Buttons for invoking macros quickly.
  • ⏺ (Record): Starts and stops action recording.
  • ⚡ (Saved macros): Opens a dropdown of your saved macros; click one to run it directly. "+ New Macro" opens Macro Studio, and each entry's right-click menu offers "Edit in Studio".
  • Macro Studio: The standalone window where macros are created and edited (see Macro Studio).

How Execution Works (the zen.* API)

Under the hood, a macro describes app operations using the dedicated zen.* API. The main calls are:

  • Navigate (navigate) / Search (search)
  • Create folder (createFolder) / Move (move) / Rename (rename) / Copy (copy) / Delete (delete, to the Recycle Bin)
  • Notify (notify) / Log (log)
  • Asking at run time (confirm for yes/no, prompt for text, promptFolder for a folder)

  • Calling the app's own features (action): zen.action("FileList.BatchRename") reaches the ~100 actions listed on the keyboard-shortcut screen, so compression, extraction, Grep, folder compare, sync, batch rename, hashing, favourites and the rest are available even though the macro vocabulary has no call of its own for them. Misspelling an action produces an error naming the closest matches. An action is only started, not waited for, so put a "⏱ Wait" after it if the macro goes on to touch the result

  • Safety: File operations (create, move, rename, copy, delete) are confined to the folder currently being displayed, and their safety is validated before they run. Using ..\, writing an absolute path that points elsewhere, or naming a neighbouring folder whose name merely looks similar (work2 while work is open) all stop before anything happens, and escaping through a shortcut — a symbolic link or junction — is closed off the same way. The folder you currently have open cannot be named as the target of a delete, move or rename either. On top of that, a single macro run is capped at 500 destructive operations.

  • It can be stopped: While a macro runs, Macro Studio's toolbar shows "⏹ Stop". Pressing it interrupts the run on the spot, and everything done up to that point comes back with a single Ctrl+Z. Stop applies to macros started anywhere — the studio's ▶, the nav pane list, the status bar, a keyboard shortcut or the command palette. No macro starts while another is running, which keeps the same macro from being launched twice and fighting itself over the same files.
  • Failures name the line: Errors read ❌ Error: line 3: ..., so where it fell over is part of the message. Typos (syntax errors) report their line the same way.
  • Undo as one step: Everything a macro does can be rolled back together with a single Undo (Ctrl+Z). Deletions (delete) are the exception — sending a file to the Recycle Bin is outside Ctrl+Z elsewhere in the app too, so a macro that deleted anything says so at the end of its output (restore those items from the Recycle Bin). If anything could not be rolled back, the notification reports how many failed and which ones.

Action Recording

You can capture your actual operations and turn them into a macro.

  1. Press ⏺ (Start recording) on the status bar.
  2. Work as usual — navigate folders, search, and so on.
  3. Stop recording. Your operations are converted to JavaScript, and Macro Studio automatically opens on the Code tab with a fresh new macro.

From there you can run it, edit it, or name and save it.

AI Integration

With zen.ai you can ask the AI to classify files or propose organizing actions, then run operations based on the result (this requires a generative-AI setup; see AI Provider Settings for how to configure it). It's available as the "🤖 AI Organize" block in Macro Studio's parts palette.

Saving and Reusing

Name and save your macro from Macro Studio (macros are stored in the macros folder inside the data folder). Editing and saving an already-saved macro overwrites it (use "Duplicate" first if you want to keep it as a separate new macro). Saved macros can be invoked from:

  • The list in the "Macros" view of the nav pane (double-click or ▶ to run)
  • The ⚡ (Saved macros) dropdown on the right side of the status bar (click to run)

Triggers (Automatic Execution)

Each saved macro can be given conditions (triggers) for running automatically. Configure them from Macro Studio's properties column (shown only while editing an already-saved macro).

  • 🏁 On startup: Runs automatically when the app starts.
  • ⏰ Daily: Runs automatically every day at a specified time (HH:mm).
  • ⌨ Hotkey: Runs with a shortcut key you assign (e.g., Ctrl+Shift+M).
  • 👁 Watch (hot folder): Runs automatically when a specified folder changes.

Configured triggers appear as badges in the nav pane's list and in Macro Studio's library column.

Using Macros Safely

  • Confirm before running: A confirmation dialog via zen.confirm and pre-run validation (dry run) help prevent unintended data loss.
  • Unsaved-change protection: While editing in Macro Studio, switching the library selection, starting a new macro, or closing the window with unsaved changes prompts a discard-confirmation dialog.
  • Free-version limits: AI features and macro execution have a limit on the number of uses in the free version (the Full version is required to use them without that limit).

Macro Studio

Macro Studio opens from the nav pane's "+", a saved macro's right-click "Edit in Studio", the status bar's "+ New Macro", and similar entry points. Part names, their descriptions, the example inputs and even the presets are available in all ten languages, following your display-language setting. It's the sole place macros are created and edited, and it's modeless (a separate window), so you can keep browsing and operating on folders in the background while it is open. It has three columns:

  • Left: Library column — The list of saved macros. Selecting one switches the edit target (with a confirmation if there are unsaved changes). Right-click to duplicate, export or delete.
  • Passing macros around: "Export…" in the right-click menu saves a macro as a single .json, and "Import…" in the column header brings one in. Before importing, you see what the macro does — deletes files, moves them, sends a request to the AI and so on — and decide from there. An imported macro does not run: it opens in the studio so you can look it over. Its id is reissued on import, and its triggers (startup, schedule, watch, shortcut) are not carried over, so a macro someone sent you never starts running the moment it arrives.
  • Center: Editing area (Node / Code tabs)
  • Node tab: Build macros by combining parts (blocks) like a puzzle on a large 2D canvas.
    • Let the AI build it: Type what you want in the field above the canvas and press "✨ Generate" — the macro appears on the canvas already assembled (for example, "file the PDFs into monthly folders and notify me"). What comes out is an ordinary macro, so you can keep adding parts and editing arguments. Generating does not run it — look it over, then press "▶ Run". If it isn't what you meant, reword the request and press Generate again. The name of the folder you have open and what is in it (the first 40 items) are sent along, so phrases like "the selected files" make sense to it (the folder's full path is not sent). If the canvas already holds nodes, you are asked before they are replaced. Requires an AI provider (AI Provider Settings). While it works, "Cancel" stops it.
    • Tidy the layout: "≡ Tidy" at the top-left of the canvas re-arranges the cards to follow their connections — a straight run into a single column, a branch sending "yes" down and "no" into the column to its right, and a loop putting its body in the column to the right with what follows it below. It is the same layout the AI generator uses, so hand-built and generated macros look alike. The cards are not rebuilt: connections and the values you typed stay as they are, only the positions move. Cards connected to nothing are gathered in a column at the right.
    • Canvas navigation: Left-drag empty space to pan the canvas. Hold Shift and left-drag to marquee-select a rectangular area, so you can select and move several cards at once.
    • Place parts: Drag & drop blocks from the "Parts" palette on the left onto the canvas (clicking also adds them). Hovering over a part shows a description of what it does. Selecting a card highlights parts that naturally follow its output with a "★ Suggested" badge in the palette, so you always know what to add next (it learns from the combinations you actually use).
    • Connect: Wire the "sockets" (connectors) on the left/right of blocks together to set the run order (upstream → downstream). Connection lines automatically route around cards instead of overlapping them.
    • Configure (in the right pane, just pick): Click a card and its "Part settings" open in the right pane. The card itself only shows what the part is and its current value; you change the value here — far easier than typing inside a narrow card. Depending on the field type, the inputs offer "📁 Browse (folder picker)", a dropdown of the current folder's contents, "{ } Tokens" (insert the date and similar), and "▾ Presets" (commonly used values), so you can configure them with minimal typing. The same place shows what the part does and the JavaScript it produces. The selected card is outlined in the accent colour.
    • Conditional branching: The "🔀 Branch" block has two outlets, "Yes / No". You can split the flow by a condition (has selection / has items / confirmed OK / file exists / custom expression); at run time it is converted to if / else.
    • Repeat: The "🔁 Repeat" block has two outlets, "repeat" and "afterwards". What you connect to "repeat" is the body; what you connect to "afterwards" runs once the loop is done. Choose what to walk over — the folder's contents or the selected items — and optionally add a filter such as *.pdf (filters do not apply to a selection). Inside the loop the current item is available as {item} (name), {itemExt} (extension), {itemPath} (full path) and {itemDate:yyyy-MM} (modified date) — these tokens only mean anything inside a loop. Something like "file all the PDFs into monthly folders" can be built without writing any script.
    • Asking for a value at run time: Writing {prompt:Enter a prefix} in an argument brings up an input box when the macro runs and drops what you type into that spot; {promptFolder} opens the folder picker instead. One macro can then be reused with different values. Cancelling the input stops the macro then and there.
    • Script part: The "🧩 Script" block lets you write JavaScript directly, in the right pane's "Part settings". Use it for anything the other parts cannot express — walking a list and branching on a condition, such as sorting by extension or moving only the files above a certain size. What you write becomes part of the macro as-is (the available calls are the zen.* API in How Execution Works (the zen.* API)).
    • Example parts: Navigate, Create Folder, Rename, Organize-Move, Copy, Delete to Recycle Bin (recoverable), Search, Notify, Log, New Tab, Go Up, Go Home, Refresh, Wait, AI Organize, Sequential Rename, Branch, Repeat, Script.
    • Adjust card width: Drag the grip on the right edge of each node card left/right to change its width. Growing a card, or dragging it to a new position, automatically nudges any overlapping downstream card out of the way.
  • Code tab: Shows the generated JavaScript. Hand-written or freshly-recorded macros (with no node graph) can be edited directly here. Macros that originated from a node graph are read-only here, to prevent an accidental overwrite from a stale hand-edit — edit those in the Node tab instead. Line numbers are shown and keywords, strings, numbers and comments are coloured — the colours come from the theme, so the code stays readable whichever one you use. The "🧩 Script" part's editor looks the same.
  • Right: Properties column — The top section is "Part settings" for the selected card (click a card to open it). Below that you edit the macro's name and description, and for an already-saved macro configure triggers (startup / daily / hotkey / watch). The most recent run output is always pinned at the bottom.
  • Run history: Opening "Run history" below the output lists the last 30 runs, newest first, with the time, the macro's name, whether it succeeded, and how long it took. The mark at the start of each row is where the run came from: ▶ manual / ⏻ startup / ⏰ schedule / 👁 folder watch. Hovering shows a summary of the result — the reason, when it failed. This is where you check whether an automatic run actually happened. The list keeps 200 entries, dropping the oldest, and "Clear history" empties it.
  • Toolbar: "+ New" resets to a fresh new-macro state, "▶ Run" executes, "⏺ Start Recording" / "⏹ Stop Recording" toggles action recording, and "💾 Save" saves (overwriting the macro currently open, if any).