1. Welcome to FileWorks

mainScreen

FileWorks is a fast, lean dual-pane file manager for macOS — in the tradition of the classic "commanders". Instead of a single Finder window, you see two folders side by side. One pane is the source, the other the destination: copying, moving and comparing becomes a matter of a single keystroke.

Through all of this, FileWorks stays close to the Mac. It uses the system’s own Quick Look, the same icons, Finder comments and Finder tags — and it feels instantly familiar next to Finder. At the same time you get the things Finder is missing: a real queue for copy jobs, browsable archives, multi-rename, colour rules, selection by pattern, your own tools and thorough keyboard control.

And if you would rather work with just one folder: you can hide the second pane at any time ( + + 2). FileWorks then becomes a tidy single-pane manager, with no loss of features.

Table 1. A few terms up front
Term What it means

Panel (pane)

One of the two file lists. Each panel works on its own and has its own tabs.

Active panel

The panel you last clicked in. A coloured bar along the top shows which one it is. Almost every command acts on the active panel; "the other panel" is the target for copying and moving.

Tab

A folder open inside a panel. Each panel can keep several tabs open, shown in a bar along the bottom edge.

Queue

The list of running copy and move jobs. It appears at the bottom of the panel and shows progress, speed and errors.

Shelf

A small collecting area ("Drop Shelf") at the top of the sidebar, where you can park files from different folders.

Disclaimer Regarding Third-Party Applications
This user manual references various third-party applications for illustrative purposes only. All applications, software products, trademarks, service marks mentioned herein remain the exclusive property of their respective owners and copyright holders.
We expressly disclaim any ownership, affiliation, sponsorship, or endorsement of these third-party applications. No rights to any intellectual property are claimed or implied through their inclusion in this documentation.
The referenced applications serve purely educational and demonstrative purposes to illustrate:

  • Different implementation methodologies

  • Common integration patterns

  • Typical use case scenarios

Important Notes:

  • The inclusion of any application does not constitute a recommendation, endorsement, or guarantee of its functionality, security, or suitability

  • Users should independently verify the legitimacy and safety of any third-party applications before use

  • Application availability, features, and URL schemes may change without notice

  • We assume no responsibility for the content, privacy practices, or terms of service of referenced applications

All trademarks and registered trademarks mentioned are the property of their respective owners and are used here solely for identification purposes in accordance with fair use principles.

2. The Main Window

mainScreen2

The window is made up of four areas:

  • the sidebar on the left (can be hidden),

  • the left and right panel in the centre,

  • the optional inspector on the right, and

  • the toolbar along the top.

Between the two panels sits a divider you can drag to shift their widths. It snaps to the centre (with a soft click on trackpads), and a double-click re-centres it exactly.

2.1. Anatomy of a Panel

Panel

A panel is built from top to bottom like this:

Active bar

A thin coloured strip right at the top. On the active panel it glows in the accent colour; on the inactive one it stays empty — the quickest way to see which panel is currently "in charge".

Header

On the left a house icon that opens a list of all volumes (Home and every attached drive); a click switches there. Next to it the path bar (see Navigating) and below it the status bar.

Status bar

Normally shows the number of items. As soon as you have marked or selected something, it shows the count and the total size (see Selection and Marks). Inside an archive there is a read-only note with the archive name; otherwise the free space of the drive. Errors appear here in red.

Action toolbar

A narrow strip of buttons between the header and the list (see The Panel Action Toolbar).

File list

The folder contents, as a list or as an icon grid.

Footer

On the left the mask field (see Selecting by Mask), on the right the tab bar.

2.2. The Window Toolbar

The toolbar at the very top carries the global commands — the ones that are not tied to a particular panel:

Button What it does

Back / Forward

Step through the recently visited folders of the active tab.

Second Panel

Show or hide the right panel ( + + 2).

View

Switch the active panel between list and icons.

Sort

Choose the sort field and direction for the active panel.

Share

Share the selection via AirDrop, Mail, Messages or a share extension. The button shows the usual macOS panel right below it. Enabled once real files or folders are selected — inside an archive it stays greyed out, as those entries have no file on disk.

Hidden Files

Show or hide hidden files.

Transfers

Show or hide the queue manually.

File Info

Show or hide the inspector ( + + I).

2.3. The Panel Action Toolbar

sidePanel

The vertical strip beside each list brings the most important file commands right to the edge — one click, no detour through a menu or the toolbar. A button dims when its action is not possible right now (for example New Folder in a read-only archive), and in the inactive panel the whole strip is greyed out.

  1. Jump list for accessing drives and favorites (see [sprungliste])

  2. Switch the following toolbars between Standard, Tools, and Both (also available using + + B)

Toolbar for included actions

  1. Copy

  2. Move

  3. Duplicate

  4. Edit

  5. Smart Select

  6. Smart Deselect

  7. Rename

  8. New Folder

  9. Compress

  10. Delete

  11. Refresh

Toolbar for custom tools

  1. Toolbar for your own tools — see Custom Tools

sidebar

The sidebar (show/hide with + + S) contains, from top to bottom:

Drop Shelf

A collecting area for parking items — see The Drop Shelf.

Favorites

Your favourite folders. A click opens one in the active panel; the context menu also offers Open in Left/Right Panel and Open in New Tab. You manage the list under Settings  Favorites.

Volumes

All attached drives, with an eject button for removable and network drives.

Network

Saved servers (see Connecting to Network Volumes) and a Connect to Server … button.

Tags

The Finder tags you use, each with its colour. A click finds every file that carries that tag. The section stays hidden until you have at least one tag — see Tags.

3.1. Opening Folders and Moving Around

  • You open a folder with a double-click (or, in the list, with ).

  • + goes to the enclosing folder — as does the up-arrow in the path bar.

  • Back and forward: + / + (alternatively ⌘[ / ⌘]) step through the recently visited folders.

  • + + H jumps to your Home folder.

A small detail that saves a lot of time: when you go up a level, the folder you came from is selected again straight away. So you can just keep hopping with the arrow keys.

3.2. The Path Bar

pathbar

The path bar shows the current location as a row of clickable folders. A click on one jumps straight there. If the path is longer than the panel, the bar slides so the current folder stays visible.

Between two folders you see a small chevron. Click it and a menu of the neighbouring folders at that level opens — a quick jump into another folder alongside, without the detour up and back down.

3.3. Go to Folder

With + + G you type a path directly. The field understands absolute paths, ~ for your Home folder, and paths relative to the current folder. As you type, it suggests matching subfolders: / selects, completes, opens, esc cancels.

3.4. Favorites and volumes: the jump list

The drive icon at the top left of a panel opens the jump list — or press + 1 for the left panel and + 2 for the right one. It holds your favorites, with every attached drive below them; wherever you currently are carries a tick.

volumepopover01

The real gain is the keyboard: just start typing. With every character the list narrows to the matching entries, and the first hit is selected right away. In practice that means:

+ 1 · dow · — and the left panel sits in your Downloads folder.

The matching is forgiving: it ignores capitalisation and accents alike. So grosse finds a folder called Größe, and doc is enough for Documents.

Table 2. Keys in the jump list
Key What it does

/

Move through the list.

Home / End

Jump to the first or last entry.

Open the selected place in this panel.

+

Open it in the opposite panel — if that one is hidden, it appears for the purpose.

esc

Clears the filter first; a second press closes the list.

For drives, a slim bar shows how full they are, with the free space beside it. When it gets tight the bar turns orange, and red on an almost full drive — so you can see whether anything still fits there before you even jump.

+ is the quickest way to line up a destination: you stay on the left with your files, and + 1 followed by + sends the backup drive to the right — without taking your hands off the keyboard.

The same overview — plus eject buttons — is in the Volumes section of the sidebar. Which folders appear as favorites you decide there as well (a folder’s context menu: Add to Favorites).

3.5. Tabs

Each panel has its own row of tabs along the bottom edge.

  • + T opens a new tab (the + button does the same).

  • + W closes the current tab.

  • + and + + step through the tabs — the same keys as in Safari or Terminal.

  • A tab’s context menu offers Duplicate Tab, Close Tab and Close Other Tabs.

By default your tabs are back the next time you launch. If you prefer a fresh start, turn that off under Settings  General.

4. Viewing Files

4.1. List and Icon Views

listStyles

Each panel shows its contents either as a list ( + + 1) or as an icon grid ( + + 2). FileWorks remembers the choice per panel.

The list is a table you can sort via the column headers. The icon grid can do everything you expect: drag a selection rectangle from an empty area, -click and -click, -click to mark, type to jump (type-ahead), and arrow-key navigation in all four directions.

4.2. Columns and Sorting

A click on a column header sorts by it, another reverses the direction. The same fields are in the Sort menu: Name, Extension, Size, Modified and Kind. With Sort folders first enabled (the default), folders always come before files, whatever the sort field.

Which columns you see is set under Settings  GeneralColumns: Extension (as its own column — the name is then shown without the extension), Size, Modified, Kind and Finder Comment. The Name column is always there.

The size of an application or another package (.app, .bundle …) is worked out recursively by FileWorks, just like Finder does. The value is computed in the background and appears shortly after loading; plain folders show "—" until then.

4.3. Thumbnails, Colours and Hidden Files

  • Thumbnails — images, videos and PDFs show a small preview instead of a generic icon (toggle under Settings  General).

  • Colours — files are tinted by their extension, according to your colour rules (see Colours).

  • Hidden files — show and hide with + + ..

4.4. Quick Look

Space shows the selection in Quick Look, exactly as in Finder. The arrow keys page through the selected items inside the preview window; Space or esc closes it again.

If an item is inside an archive, FileWorks first extracts it briefly into a cache. If that takes a moment (large archives), a progress bar with a Cancel button appears.

4.5. The Inspector (File Info)

You turn the inspector on with + + I. It shows the details of the single selected item in the active panel:

  • a large preview (real content for images, PDFs and videos, otherwise the file or app icon),

  • general details — path (with a Show in Finder button), size, created, modified and added dates, extension, hidden or not,

  • for images, additionally: dimensions, resolution, colour model, colour profile, bit depth and alpha channel,

  • the file’s Tags, which you add or remove here (see The Inspector Tag Editor),

  • the Finder comment, which you edit here (see below).

If several items are selected, the inspector shows a summary with the total size instead.

4.5.1. Editing Finder Comments

The comment field writes the Finder comment straight to where Finder keeps it too — without any detour through AppleScript. Type your text and press Save. In FileWorks (and in the Comment column) it is there immediately; Finder itself shows it once Spotlight has re-indexed the file, usually after a few seconds.

5. Selecting Files

FileWorks gives you two ways to gather files. Once you understand the difference, you will work with them noticeably faster.

5.1. Selection and Marks

The selection is the familiar macOS highlight — the row (or rows) under the cursor. It follows the arrow keys and a single click. The cursor-related commands act on the selection: Rename, Quick Look, the inspector and opening a folder.

Marks are a second layer on top — the classic commander trick. A marked item wears a coloured pill around its icon and name (in the icon grid, around the whole tile). The key difference: marks stay. You can move the cursor, click elsewhere, filter — the marks hold until you clear them or leave the folder.

And that is exactly what makes them so useful: almost all file commands — Copy, Move, Duplicate, Delete, Edit, Pack, Multi-Rename, Create Link, Add to Drop Shelf and your own tools — act on the marks, when there are any, otherwise on the selection. So you calmly mark a batch and then work on it, without fear that a stray click undoes everything. The status bar shows it: "N of M marked".

If you never mark anything, FileWorks simply behaves like Finder — then the selection is your working set. The marks are there when you need them, and invisible otherwise.

5.2. With the Mouse

Clicking selects; -click adds or removes single items; -click selects a range. In the icon grid you can also drag a rectangle from an empty spot (with or to add to the existing selection).

To mark with the mouse: hold and click — in the list on the name, in the grid anywhere on the tile. This toggles the mark without touching the selection. The context menu also has Mark / Unmark.

5.3. With the Keyboard

The arrow keys move the cursor. In the list, + and + extend the selection into a contiguous range. + A selects everything; esc first clears the marks, then the selection.

The star of keyboard marking is + Space: it marks the item under the cursor and moves down one row. Pressed repeatedly, you mark a whole run in one flowing motion. (Plain Space stays Quick Look, as in Finder.) If you have just selected a range — say with + — then + Space folds that whole range into the marks and frees the cursor, so you can build the next block somewhere else.

select01

You can reassign both Space commands. If plain Space or + Space clashes with another program, change the modifier under Settings  GeneralSelection & Quick Look. The Space key itself stays; only the modifier changes, and the two can never become the same.

5.4. Smart Select and Invert

These commands live in the Actions menu and all produce marks — so their result is safe from a stray click:

Smart Select ( + + S)

Marks every item whose type already occurs in your working set. Example: you have selected one .zip and one .md — Smart Select marks all zip and md files in the folder.

Smart Deselect ( + + + S)

The counterpart — marks every file whose type is not in the working set.

Invert Selection ( + + I)

Marks everything that is currently not marked.

Select None

Clears marks and selection in one go.

5.5. Selecting by Mask

The mask field at the bottom left (focus it with + F) marks files by a pattern, live as you type:

  • *.pdf marks all PDFs.

  • IMG_????.jpg marks names like IMG_0421.jpg.

  • Separate several patterns with spaces or semicolons: .jpg;.png.

  • Text without wildcards is searched as part of a name.

Because the mask marks rather than selects, the matched set stays put when you click into the list afterwards. By default only files are marked; to include matching folders, enable Settings  GeneralSelect by MaskInclude folders. hands focus to the list, esc clears the field.

6. Working with Files

6.1. Copying and Moving

Mark items in the active panel and press F5 to copy or F6 to move them to the other panel. The same commands are on the action toolbar, in the context menu and in the Actions menu ( + + C / + + M).

In single-pane mode there is no "other panel" — then FileWorks asks for a destination folder (see Single-Pane Mode).

If source and destination are on the same APFS drive, it is near-instant: copying uses immediate clones (copy-on-write), moving just a rename. Permissions, timestamps, extended attributes and ACLs are always preserved.

6.2. The Transfer Queue

Every copy and move job runs through a queue: one after another, the rest waiting in order. It docks at the bottom of the right (or only) panel and shows, per job, a progress bar, the current item, the speed and the estimated time remaining — plus a Cancel button.

The dock appears on its own once a job takes a little longer, and disappears again after an error-free finish. Jobs that ended with errors stay put until you clear them (the Clean Up button or the × on the card). To show the queue by hand, use the Transfers button.

6.3. Resolving Conflicts

When a job meets a matching name at the destination, a conflict dialog appears. It puts both items side by side — size, date and a "Newer" hint — and lists your options below, each with a short explanation:

Replace

Overwrite the item at the destination.

Skip

Leave the destination untouched.

Keep Both

Copy under an automatically numbered name ("Name 2").

Merge

Folder-vs-folder only — the contents are combined; for matching files inside, you are asked again.

Replace All Older

Like an incremental backup: replace only when the source is newer, skip the rest, merge folders. Applies to the whole job.

The first row is preselected: keeps both. Hold and every row shows its number; + 1 to + 5 pick one straight away. Which number belongs to which option depends on the case — Merge appears for folders only and shifts the following entries down by one.

The Apply to all further conflicts switch remembers your choice for the rest of the job — separately for file and folder conflicts.

FileWorks never leaves half files behind. Each file is first copied to a hidden temporary file and then swapped in at once. When replacing a folder, the old contents are set aside and only deleted once the new ones are fully in place — if anything goes wrong or you cancel, the old state is back.

6.4. Duplicating, New Folders and Renaming

Duplicate

Copies the selection within the same folder; name clashes FileWorks resolves on its own ("Name 2").

New Folder (F7, + + N)

Creates a folder and lets you name it right away.

New Folder with Selection ( + + N)

Creates a folder and moves the selected items straight into it — handy for gathering loose files in one go. This folder, too, is ready to rename at once. As the items stay on the same drive, it happens instantly, even for large files.

Rename (F2, + R)

Opens a dialog with separate fields for name and extension — so you change one without touching the other. A preview shows the new name and flags conflicts in red.

6.5. Multi-Rename

To give many files new names at once, select them and open Multi-Rename … ( + + R). The dialog renames by a pattern — with a live preview of every result and a check that catches duplicate targets, clashes and invalid names, blocking the rename until everything is clean.

multirename01

6.5.1. Name and Extension Masks

The name mask and the extension mask build the new name from placeholders. You type them directly or insert common ones through the + menu next to the field.

Table 3. Placeholders
Placeholder Meaning

[N]

The original name (without extension).

[N2-5]

Characters 2 to 5 of the name.

[N2,5]

5 characters starting at position 2.

[N2-]

From character 2 to the end.

[N-4-]

The last 4 characters (negative positions count from the end).

[E]

The extension (with the same range syntax as [N]).

[P] / [G]

Name of the parent / grandparent folder.

[C]

A counter, controlled by the Start / Step / Digits fields.

[C10+5:3]

A counter written inline: start 10, step 5, 3 digits (any part is optional).

[Y] [M] [D]

Year, month, day of the modification date.

[h] [m] [s]

Hour, minute, second.

[d] / [t]

Date as YYYY-MM-DD / time as HH.MM.SS (safe for file names).

[U] / [L] / [F]

Make the following characters UPPERCASE / lowercase / Word-Start-Uppercase.

[n]

Back to normal case.

[[ / ]]

Insert a literal [ or ].

An unknown placeholder FileWorks leaves as it is — so a typo stays visible instead of quietly vanishing.

6.5.2. Search & Replace, Case and Counter

  • Search for / Replace with — without RegEx you separate several terms with |; they are matched one to one to the replacements (a missing replacement deletes the term). With RegEx you use one pattern with back-references like $1.

  • Case — one mode for the whole thing: unchanged, lowercase, UPPERCASE, First letter uppercase, or Every Word Uppercase.

  • Counter — Start, Step and Digits for [C].

The order of the rows in the preview determines the counter value — drag the rows to reorder them.

A scheme you use often, save it as a preset (the Presets menu at the top of the dialog) and recall it next time with one click.

6.6. Deleting

F8 (or the Trash button) removes the selection. Whether items go to the Trash or are deleted permanently — and whether FileWorks asks first — you set under Settings  GeneralDeleting. On drives without a Trash (some SMB servers), FileWorks offers to delete permanently instead.

In the context menu you can swap the two: hold and the entry changes — if your default is the Trash it becomes Delete Permanently, otherwise the other way round. The swap happens live while the menu is open.

This pattern applies to further context-menu entries: Paste becomes Paste (Move) — just like + + V — and Copy Path becomes Copy Path as File URL.

The Create Link submenu (Actions menu or context menu) makes:

  • an alias or a symbolic link,

  • in the other panel (in single-pane mode: a folder of your choice) or here in the same folder (the name then gets the suffix " Alias" / " Link", so nothing clashes).

Aliases survive their target being moved or renamed, and work across drives. Symbolic links in the same folder are created relative, so they survive moving the whole folder.

6.8. The Clipboard

FileWorks uses the normal clipboard — compatible with Finder in both directions:

  • + C copies the selection (as file references).

  • + V pastes it into the current folder (copying).

  • + + V pastes it as a move (the originals then disappear).

In the context menu the first command is called Copy to Clipboard — spelled out, so it is clearly distinct from Copy to "…", which transfers the files straight to the other panel.

6.9. Drag and Drop

Drag items from a list into Finder or into the other panel. Dropping copies by default; with held it moves. Drag something into a panel and it lands in that panel’s current folder — drop it straight onto a folder row and it lands in that folder.

6.10. The Drop Shelf

The Drop Shelf at the top of the sidebar is a holding area. Drag files onto it — or select them and press + + D (Add to Drop Shelf, also in the context menu) — to collect them across several folders, then drag them all together into a destination (Finder or a panel).

If the sidebar is hidden when you add something, it opens briefly so you see the result. Via the list button in the shelf header you reach per-item actions and the option Keep items after dragging out — handy when the same collection should go to several destinations in turn.

dropshelf01

7. Tags

FileWorks reads and writes Finder tags — the very same coloured labels macOS also shows in the Finder sidebar. A tag you set here is a real Finder tag, and vice versa; none of it is FileWorks-only. macOS comes with seven system colours (Red, Orange, Yellow, Green, Blue, Purple, Grey), and you can add any number of your own named tags, with or without a colour.

Because FileWorks writes tags straight into the file’s metadata, a new tag appears here immediately. Finder and the system-wide tag search catch up once Spotlight has re-indexed the file — usually after a few seconds.

7.1. Assigning Tags

The quickest way is the context menu. Right-click one or more items and open the Tags submenu: it lists the seven system colours and every tag you already use, each with a check mark. A click toggles the tag on the selection:

  • If it is not yet on every selected item, it is added to all of them.

  • If it is already on all of them, it is removed from all of them.

Finder behaves exactly the same way. The coloured dot beside each entry shows the colour.

tags01

7.2. Creating a New Tag

New Tag … — in the Tags submenu of the context menu or via Add Tag in the inspector — opens a small dialog. Type a name, optionally pick a colour (the first swatch, a crossed-out circle, means "no colour") and press Assign Tag. The tag lands on the selected items and moves into your tag list, so it shows up in the sidebar and in future menus.

7.3. The Inspector Tag Editor

With exactly one item selected, the inspector ( + + I) shows that file’s tags in the Tags section as small chips to click away. Add Tag attaches a system or existing tag, New Tag … creates a new one. Remove the last chip and the file’s tags are gone entirely. See The Inspector (File Info).

7.4. Tags in the List

In the list view, small coloured dots sit next to the name of every tagged file — one dot per colour, slightly overlapping, like in Finder. Hover the file to see the tag names. (The icon grid stays deliberately tidy and shows no dots.)

7.5. The Tags Sidebar

Every tag you use appears in the Tags section of the sidebar (which stays hidden until you have at least one). Each row shows colour and name. The section is collapsible like the others; see The Sidebar.

The list is just a convenient index, not the tag itself: Remove from Sidebar (context menu) only takes the entry out of the list — the files keep their tag, and the entry comes back as soon as FileWorks sees the tag again.

7.6. Finding Tagged Files

Click a tag in the sidebar (or Find Tagged Files in its context menu), and FileWorks searches system-wide for every file with that tag — via Spotlight. The hits stream into the active panel, just like a file search (see Searching), with a Location column, and the status bar shows Tag "…": N items. From a hit, Go to Enclosing Folder jumps to the real location. Navigate away and the tag search ends.

Only files on drives that Spotlight indexes are found. Files on network shares or in excluded locations do not show up — but FileWorks can still read and write their tags normally.

7.7. Keeping in Sync with Finder

Tags you change in FileWorks are there right away. Tags changed elsewhere — in Finder or another app — FileWorks picks up automatically the next time you enter the folder (once away and back is enough). To re-read everywhere at once, press + + R (Refresh).

tags02

8. iCloud Files

If you use iCloud Drive (or another cloud service) with Optimise Mac Storage, macOS keeps the contents of some files in the cloud only, to save space. The file is still in the list, but its data does not reach your Mac until you download it. FileWorks shows you this at a glance and downloads or offloads files on demand — just like Finder.

8.1. The Status Icon

A small icon appears at the right of the name column — but only when there is something to say:

  • A cloud with a downward arrow — the file is in iCloud and not downloaded.

  • A small spinner — the file is downloading right now.

Files that are fully downloaded, and files that are not in iCloud at all, show no icon — so the list stays quiet and only flags what is not yet local. Hover the icon for a short explanation.

8.2. Downloading and Removing Downloads

Right-click one or more items for the matching action:

Download Now

Downloads the selected cloud-only files, so their contents are local. The icon switches to the spinner and disappears once the file has arrived.

Remove Download

Frees the local copy again — the file stays in iCloud and can be downloaded any time. This only removes the local copy, so it is safe and needs no confirmation (as in Finder). If a file has changes that are not yet uploaded, macOS keeps it and tells you why.

Both actions work on a whole selection and skip whatever they do not apply to.

For a single item, the inspector ( + + I) also has an iCloud section with the same Download Now / Remove Download button.

8.3. Copying and Moving Cloud Files

You do not have to download a file first to copy or move it: when a job needs a cloud-only file, FileWorks downloads its contents automatically as part of the job — so the copy is complete, never a hollow placeholder. This works with any provider (iCloud, Dropbox, OneDrive, Google Drive), because it relies on the system’s own file-provider mechanism. For iCloud you see a cancellable "Downloading …" step; other providers download quietly in the background. See The Transfer Queue.

cloud01

The status icon and the Download Now / Remove Download actions exist for iCloud only — Dropbox, OneDrive and the like show no icon and no menu entry (macOS does not expose their status the way it does for iCloud). Copying and moving still works correctly. An externally changed iCloud status (you download or offload in Finder) FileWorks picks up when you re-enter the folder, or with + + R.

9. Single-Pane Mode

Not every task needs two panels. + + 2 (or the Second Panel button) hides the right one. It is only hidden, not closed — tabs, history and selection are exactly as you left them when you show it again.

Commands that would normally address the other panel ask for a destination folder in single-pane mode:

  • Copy to Folder … / Move to Folder … (F5 / F6)

  • Alias / Symbolic Link in Folder …

  • Your own tools that need the other panel’s folder ({target} or the working directory "other panel")

The folder dialog starts at the destination you chose last time, so repeated transfers to the same place cost just one click. The queue docks at the bottom as usual.

The Drop Shelf is especially handy in single-pane mode: collect items as you browse, then navigate to the destination and drag them all out — no second panel needed.

10. Archives

With the system’s libarchive available, FileWorks simply treats archives like folders.

10.1. Browsing and Extracting

Double-click a .zip, .7z, .tar., .rar, .iso (and more) to *go in, as if it were a folder; the path bar leads you through. A read-only note in the status bar reminds you that archives cannot be written to.

  • Copy entries out (F5 to the other panel, or drag them to Finder) — the extraction runs through the queue, with progress, cancel and conflict handling.

  • Open or edit a single entry — it is first extracted into the cache, then opened.

  • Whole folder subtrees can be dragged out; extraction happens on drop.

You can turn browsing off entirely under Settings  GeneralArchives — then a double-click opens the archive with its default app.

Your own tools are greyed out inside an archive (see When a Tool Is Available). An entry you see is not a file yet — there is no path a program could open. Copy it out first, and the tool works with it normally.

10.2. Creating Archives (Pack)

Mark items and choose Pack … (Actions menu or context menu):

  • Destination — where the archive is written: the folder you are packing from, the other pane’s folder, or any folder via Other Folder …. That way you don’t have to move the finished archive to where it belongs afterwards.

  • Format — ZIP, 7z or tar.gz.

  • Compression — None (store only), Fast, Normal or Maximum.

  • Password (ZIP only) — either ZipCrypto (weak, but readable everywhere, including Windows Explorer) or AES-256 (secure, but needs 7-Zip / Keka to open).

  • Comment (ZIP only) — stored in the archive.

  • Delete sources after a successful check — turns packing into moving, see just below.

A progress bar shows the packing; Cancel removes the half-written archive again.

compress01

10.2.1. Turning a Pack into a Move

Normally the originals stay put — afterwards you have them twice, once individually and once inside the archive. Tick Delete sources after a successful check and FileWorks tidies up afterwards. But only once it has made sure.

That gives the operation three steps, which you can follow in the progress bar: packing, checking, removing. While packing, FileWorks computes a fingerprint for every file — from exactly the bytes that go into the archive. It then reads the finished archive back and compares. The sources are removed only if all three hold:

  • Nothing was skipped, so no file was unreadable.

  • The archive could be read in full.

  • Every fingerprint matches the one of the source file.

If any of these fails, the sources are left untouched and the dialog tells you why. The archive stays put in that case — you can take a look at it.

Whether the originals go to the Trash or disappear for good follows Settings  GeneralMove items to the Trash. The text next to the checkbox tells you each time what is about to happen.

FileWorks deliberately does not remember the tick: the next time you pack, it is clear again. A permanently enabled delete option is the kind of setting you turn on once and have forgotten about by the time after next.

If the archive would land in a folder you are packing, the option is disabled — deleting the source would take the archive with it.

10.3. Verifying Archives

An archive can break quietly: a transfer is cut short, a disk ages, a copy arrives incomplete. You can’t see it from the outside. The file is there, the size looks plausible — and you would notice only when extracting it, possibly years later.

Mark an archive (or several) and choose Verify Archive … from the context menu or via Actions  Verify Archive …. FileWorks then reads every entry once, in full, and throws the data away — the only question is whether it can be read without errors. Nothing is written, but it takes as long as a full extraction.

For a single archive the result sits right in the header; for several you get a list with one row per archive. Entries that failed are named individually; Copy Report puts the list on the clipboard.

10.3.1. What a Passed Check Does — and Doesn’t — Tell You

Not every format detects damage equally well. FileWorks therefore promises no more than there is; the line below the result tells you where you stand:

every checksum matches

ZIP and 7z carry a checksum for each individual entry. Here it is possible to say not just that something is broken, but which file it hit.

the checksum over the whole archive matches

tar.gz and relatives have one checksum across the entire stream. Damage shows up, but cannot be narrowed down to a single file — from the damaged spot onwards the rest is unreadable anyway.

content read in full

For all other formats FileWorks says only what it can prove: everything could be read. A plain .tar, for instance, carries no checksums over file contents at all.

10.3.2. Encrypted Archives

If an entry is encrypted, FileWorks asks for the password. Cancel the prompt and it finishes checking what it can without one — the skipped entries then appear as not checked (encrypted) in the report, and the archive does not count as intact. An unread entry is simply not a checked entry.

Old archives protected with ZipCrypto have a quirk: there, the scheme checks a password against a single byte only, so roughly one in 256 wrong passwords gets through at first. The error only shows up at the end of the entry, at the checksum. In that case FileWorks reports no damaged archive but asks for the password once more.

10.4. Password-Protected Archives

When you open or extract an encrypted archive, FileWorks asks for the password and retries if you mistype. Passwords are remembered per archive and only for the current session — they are never written to disk.

11. Checksums

A checksum is a short value worked out from the entire contents of a file — a kind of fingerprint. Change a single byte and the value looks completely different. That is what makes checksums so useful: they answer questions where name, size and date can mislead you.

FileWorks answers three of them for you:

  • Did my copy arrive intact? — comparison against a destination folder.

  • Do I have this file twice? — even when it goes by another name.

  • Is this download genuine? — checking against the value the website states.

Select files or whole folders and open Checksums … from the context menu or via Actions  Checksums ….

checksums01

11.1. Choosing an algorithm

The algorithm sits at the top right. For everyday use SHA-256 is the one to pick — it is today’s standard and the value websites usually quote. MD5 and SHA-1 are faster but count as broken: an attacker can construct two different files with the same value. They still serve to verify old checksum lists, but nothing security-related.

The ⓘ beside the menu explains each algorithm in a sentence. Switch algorithms and FileWorks recomputes everything — values from different algorithms cannot be compared.

11.2. Finding duplicate files

As soon as several files share a value, their contents are identical — no matter what they are called. FileWorks collects them into groups and gives each one a number and a colour.

You have holiday_2024.jpg, IMG_4471.jpg and Copy of holiday.jpg in the same folder. All three carry the number 1 — it is the same picture three times, under three names.

A click on the # column header brings the groups together. With a few dozen files the colour is enough; with several hundred, sorting is the real gain, because related files would otherwise sit far apart.

checksums02

For tidying up, the context menu offers Select duplicates, keep first: one file from each group is left untouched and all the others are selected. Move to Trash then does the rest. Should you select a complete group by hand, FileWorks asks first — otherwise that content would be gone for good.

Empty files are left out. They inevitably all share the same value, which says nothing about duplicate content.

11.3. Verifying a download

Reputable providers state the expected checksum alongside their files. Rather than comparing 64 characters by eye, simply paste the value into the field at the top.

You have downloaded an Ubuntu image. Copy the SHA-256 value from the download page, select the .iso in FileWorks, open the checksum dialog and press + V in the field. If it says Matches "ubuntu.iso", the file is intact.

The field is deliberately tolerant: it picks the value out of whatever you paste. Whether you copy the bare value, the whole line a3f9… ubuntu.iso from a checksum file, or something like SHA256: a3f9… — it finds it.

Better still: if the length of the pasted value matches a different algorithm, FileWorks switches by itself. Paste a 64-character value while MD5 is selected and it moves to SHA-256 on its own.

While a check is running, the duplicate group colours rest and only the matches are marked green — two colour codings at once would be impossible to tell apart. Clear the field and the groups are back.

11.4. Comparing two folders

This is the answer to "is my backup complete and intact?". Select the files or folders you want to check and choose Compare … in the dialog. FileWorks offers the opposite panel as the destination — that is what two panels are for — or you pick any folder.

Every row then gets a verdict:

Result Meaning

Identical

Present in the destination, contents equal byte for byte.

Different

Present, but the contents differ.

Different size

Present, yet the size alone does not match — so the contents cannot be equal.

Not present

Nothing of that name exists in the destination.

Found n×

Several files carry that name; which one is meant is not settled.

Unreadable

The file could not be opened — missing permissions or a faulty drive.

checksums03

Below the list stands the tally — how many are identical, differing, unclear or missing. The Only differences tick hides everything that matched: with 500 files you want to see the three problem cases, not 497 ticks.

Select folders and the comparison reaches across all subfolders. Matching then goes by the path within your selection, not merely by file name. If 2024/Q3/report.pdf sits in the destination as archive/report.pdf, it rightly counts as not present — it is somewhere else, after all.

With folders, FileWorks deliberately computes nothing in advance. Only the comparison decides what actually has to be read — differing sizes are settled without a single read access. If you want all the values anyway, press Compute all.

11.5. Working with the results

The dialog does not merely display, you can act straight away. Right-click a selection — or use the buttons at the bottom left:

  • Copy to destination — transfers missing and differing files into the comparison folder. The folder structure is preserved: 2024/Q3/report.pdf lands under 2024/Q3/ there too, and missing intermediate folders are created.

  • Check again — revisits individual rows without repeating the whole comparison. Handy once you have put something right.

  • Select — picks up all missing, all differing or all unclear rows in one go. With thousands of files this is what makes acting on them possible at all.

  • Move to Trash, Show in Finder, Reveal in panel, Copy path — as usual.

Select → All missing followed by Copy to destination brings an incomplete backup up to date in two clicks.

11.6. Checksum files

Many downloads come with a file such as SHA256SUMS listing the expected value for each name. FileWorks reads those, and writes them too.

  • Compare … → Use checksum file checks your selection against such a list. The results appear in the same column as with a folder comparison.

  • Export → As checksum file writes your values in the format that shasum -c and sha256sum -c read in Terminal. That way someone else can verify your files without owning FileWorks.

  • Export → As CSV is meant for spreadsheet programs.

The common spellings are understood — with one or two spaces, binary mode with an asterisk, and the BSD form SHA256 (file) = value. Comment lines and lines matching no pattern are passed over: one broken line does not render the rest of the file useless.

11.7. Internals and limits

For every algorithm on offer the same holds: two files that differ by chance yet share a value are so unlikely that it does not happen in practice. "Same checksum" here reliably means "same contents". Only with deliberately constructed files can this be subverted for MD5 and SHA-1 — one more reason to stay with SHA-256 when in doubt.

How many files are read at once depends on the drive: on a network share one after another, because they all share the same line; on the internal SSD several in parallel. During a comparison this applies to each side separately — source and destination usually sit on different drives and do not get in each other’s way.

Folders and packages such as .app or .macvm have no checksum of their own — they are directories. FileWorks therefore resolves them into their individual files. For the question of whether a package arrived intact, every file inside it is what counts anyway.

Very large selections are deliberately reined in: from around 20,000 files the dialog asks whether you really mean that many, and beyond 40,000 it declines. For holdings of that size a purpose-built tool is the better choice.

12. Searching

FileWorks knows three ways to find something — all focused on the active panel. Which one fits depends on what you plan to do next:

Select by Mask ( + F)

Marks matching items in the current folder (see Selecting by Mask). Best when you want to do something with the hits right away — copy, delete …

Quick Filter ( + + F)

Hides everything whose name does not contain the typed text — live, so the list shrinks to what matters. With a match counter, per tab; esc clears and closes it.

Find Files ( + + F)

A recursive search from the current folder. Results stream into the list live, with a Location column. Works inside archives too. Use a pattern (*, ?) or just part of the name. From a hit, Go to Enclosing Folder jumps to the real location.

search01

13. Editing and Opening Files

A double-click opens a file with its default app. For a deliberate edit there is F3 (or + + E, or Edit in the context menu).

Under Settings  Editing you register editor apps together with the extensions they are responsible for (an empty extension list means "all files"). Then:

  • exactly one matching editor → it starts directly,

  • several match → you choose in a dialog,

  • none match → the file opens with its default app (as with a double-click).

A single folder or archive FileWorks opens for you to go in instead; archive entries are extracted first. If you want to open more than 10 files at once, it asks first, just in case.

13.1. The Chooser Dialog

When several programs match, FileWorks lays them out for you to pick from. Set apart at the very top sits the file type’s default app — even if you never registered it as an editor. In practice it is what people mean most often.

The dialog works entirely without the mouse:

  • Arrow keys move the selection, opens, esc cancels.

  • Type the first letters of a name to jump straight to it.

  • Hold and every row shows its number — + 1 to + 9 open immediately.

Programs that are no longer on the machine are not listed at all. They could not be launched anyway, and would only shift the numbers of the remaining rows.

13.2. Opening Once With a Different App

Sometimes you want to open a file somewhere else just this once — that HTML document in a text editor rather than the browser. For that, the context menu of a single file offers Open With. It lists every app that can handle this file type:

  • The default app comes first, marked "(Default)" and set off by a separator — it is also the one a double-click uses.

  • Below it, the remaining apps follow alphabetically, each with its icon.

The list comes from macOS itself — the same one the Finder shows. There is nothing to set up: install a new app and it appears on its own.

Open With only appears for a single, real file — not for folders, not for a multiple selection, and not for entries inside an archive (copy those out first). The permanent "always open this extension with that app" mapping is what Settings  Editing is for.

14. Connecting to Network Volumes

+ K (Go  Connect to Server …) mounts a network drive: SMB, AFP, NFS, FTP or WebDAV. Enter an address such as smb://server/share, optionally a user name and password.

With credentials, FileWorks connects directly and switches the active tab to the mount point. Without them — or if the direct connection fails — the usual macOS connection dialog takes over, keychain and all; the drive then appears under /Volumes and in the sidebar.

You can remember a server in the sidebar (and under Settings  Network) by enabling Remember in sidebar. Passwords are not stored — that is the macOS keychain’s job. A remembered server connects with one click; Connect with Password … opens the pre-filled dialog.

FileWorks does not store passwords itself. When you connect without a password, macOS shows its own login dialog and the keychain remembers the credentials.

15. Opening a Terminal

Open Terminal here ( + + T, also in the context menu of the empty area) opens the active panel’s folder in a terminal. Inside an archive it opens the folder that contains the archive file. By default the macOS Terminal is used; under Settings  GeneralTerminal you can choose another app (e.g. iTerm).

16. Custom Tools

With custom tools you teach FileWorks your own moves. Anything you do again and again by hand — open images in a particular app, quickly back up a few files, turn JSON files into readable ones — becomes a button that does exactly that at the press of a key.

And don’t worry: you don’t have to be a programmer for this. The simplest tool is set up in half a minute and just opens the marked files in an app of your choice — no script, no command line. If you feel like it, you can go a step further later and let small scripts rebuild whole stacks of files. Both live in the same place.

You set up tools under Settings  Tools. After that you can reach them in three places:

  • in the Tools menu in the menu bar,

  • in a file’s context menu, under Tools — where only those tools appear that suit the items you clicked,

  • and — if you like — as a button in the side action toolbar of each panel (you switch that toolbar on with + + B).

tools01

16.1. Your First Tool in One Minute

Let’s start with the simplest case, no script at all. Suppose you always open your images in the same app — say Pixelmator. Here’s how you build yourself a button for it:

  1. Open Settings  Tools and click + at the bottom of the tool list.

  2. TypeLaunch app with selection.

  3. App → choose Pixelmator (or whatever you use).

  4. Name → "Open in Pixelmator" (left empty, FileWorks uses the app’s name).

  5. Done. Close the settings.

Now mark a few images, open the Tools menu — and your new entry opens them all in Pixelmator. That’s it. No $, no quotes, nothing.

For a tool like this, set Available to "For certain file types" and enter jpg, png, heic. Then the button only lights up when images are really marked — and stays quietly out of the way otherwise, instead of leading you astray.

16.2. The Four Kinds of Tools

Every tool is one of these four kinds. Pick the one that fits your task:

Launch app with selection — the simplest case (the example just now). You pick an app, and the tool opens the marked files in it. Nothing more: no arguments, no output, no script. A fixed "Open With …" as a button.

Run program / script — here a program or a small script of yours runs, and you decide which files and values it gets. This is the choice as soon as a ready-made program (such as sips, ffmpeg, jq) or your own script should do the work.

Run shell command — for quick one-liners on the command line. A tool of this kind runs a single line through the shell (zsh), with everything that belongs to it: pipes (|), chaining (&&), redirections. Ideal for trying something out quickly.

Run shortcut — starts a shortcut from the macOS Shortcuts app and hands it the marked files (see Using Shortcuts from the Shortcuts App). Ideal when you have already built your automation there.

If you are just starting out: stick to the first kind as long as it is enough. The others we explain step by step — with examples to build yourself.

16.3. What a Tool Works On

A tool works with the files you have just marked (the coloured pills). If you have marked nothing, it takes the current selection — that is, the row under the cursor. This set we simply call the tool’s working set in this chapter.

The difference between selection and marks is described in the chapter "Selecting Files". For now this is enough: mark the files the tool should work with, then run it.

16.4. Placeholders: Telling a Tool Which Files It Gets

A tool has to know what to work on. That is what placeholders are for — short tokens that FileWorks replaces with the real values when it runs. The most important one is {paths}: it stands for "the paths of all marked files".

An example. The program wc counts lines. If you enter as a shell command

wc -l {paths}

and mark three text files, FileWorks turns it into this when you run it:

wc -l /path/to/one.txt /path/to/two.txt /path/to/three.txt

So wc gets the three files and counts their lines. You yourself only type {paths} — FileWorks fills in the rest.

You don’t have to memorise the placeholders. In the tool editor there is a glossary of all of them. Click one and it is inserted where you last typed. Hovering shows you what it will insert.

These are the placeholders:

Table 4. What the placeholders insert
Placeholder Stands for

{path}

The path of the first file of the working set

{paths}

The paths of all files

{name}

The file name of the first file, with extension (e.g. holiday.jpg)

{names}

The names of all files

{stem}

The name of the first file without the extension (e.g. holiday)

{ext}

The extension of the first file, without the dot (e.g. jpg)

{dir}

The folder the active panel is currently showing

{target}

The folder in the other panel

{?Your question}

Asks you for a value when it runs — see Asking for a Value ({?…})

Singular or plural? This is the one stumbling block, and it is quickly explained:

  • {path} is one file — the first. Use it when your tool handles exactly one file per run.

  • {paths} is all files — cleanly separated, one after another. Use it when your program takes a whole list at once.

Rule of thumb: the plural placeholders ({paths}, {names}) become one value per file, not one long piece of text. Mark three files and your program really gets three separate entries.

Never put a placeholder in quotes yourself. Even if a file name contains spaces, brackets or other special characters — FileWorks takes care of it. Just write {path}, not "{path}". This holds for all kinds of tools. Why it is safe is explained at the end under For Power Users: Security and Internals — for everyday use you only have to do it this way and not think about it further.

16.5. Asking for a Value ({?…})

Sometimes a tool should work a little differently each time. Instead of building a separate tool for every variant, you let FileWorks ask when it starts.

For this you write, at the spot where the value should go, a question in curly braces with a question mark: {?Your question}. When it runs, an input field with exactly that label appears, and what you type is inserted.

An example: shrinking images to a width you choose. As arguments you enter (using Apple’s sips program):

-Z {?Longest edge in pixels} {path} --out {stem}-small.{ext}

Run the tool and FileWorks asks: "Longest edge in pixels". You type, say, 1200, and the image is shrunk to 1200 pixels and saved as …-small.jpg next to the original. A single tool for every size — instead of one tool per size.

A few things worth knowing:

  • You are asked once per run, not per file. Shrink twenty images at once and you type the size once, and all twenty use it.

  • The same question is asked only once. Use {?Suffix} in several places and one field fills them all.

  • Cancel means cancel: dismiss the prompt and nothing happens at all.

  • The question may contain spaces ({?Longest edge in pixels} is a single question) but no curly brace {.

  • Short, clear questions are best — and name the unit: "Quality (1–100)", "Longest edge in pixels", "Suffix".

16.6. Transforming Files: Input and Output

Up to here tools have done something (opened files, counted). It gets really handy when a tool transforms files — and the result lands straight in the right place. That is exactly what the Input and Output settings are for.

The idea behind it is simple: many programs read something in, change it and write it out again. FileWorks can feed your files in at the front and receive the result at the back:

File  →  program  →  result

Input decides how the file reaches the program:

  • None (the normal case) — the file arrives as a path, just as we did above with {path} / {paths}.

  • Contents of the selected file — the contents of the file are "poured" straight into the program. You need this for programs that only read a stream and expect no file name.

Output decides what happens to the result:

Table 5. Where the result goes
Output What happens

Discard

The result is thrown away. For tools that do something themselves (write a file, show a notification) and need no return value.

Show in a window

The result appears in a console window to read. Perfect for trying things out.

Write to a new file

The result becomes a new file, named after a template such as {stem}.sorted.{ext}. If the name is already taken, it becomes "name 2", "name 3" … — a new file never overwrites an existing one.

Replace the source file

The result replaces the very file it came from. The one mode that deliberately overwrites — replacing is its whole point.

Copy to the clipboard

The result lands on the clipboard, ready to paste.

Two examples make it concrete:

Make JSON readable. JSON files are often a single long line. The program jq formats them nicely. As a tool:

  • Type: Run program / script, Program: jq, Arguments: .

  • Input: Contents of the selected file

  • Output: Replace the source file

Mark a .json file and click, and it is nicely formatted in place.

Make a sorted copy. The same with sort, but Output → Write to a new file with {stem}.sorted.{ext}. You get a sorted copy next to the original, and the original stays untouched.

"Replace the source file" is safer here than by hand. On the command line the obvious command sort < notes.txt > notes.txt destroys the file — the shell empties it before sort could read it.

FileWorks never does that. The result is first collected fully in a hidden file and only put in place once the program has finished cleanly (without errors). If anything goes wrong or you cancel, your original stays exactly as it was.

16.7. Adding Your Own Scripts

When a task outgrows a one-liner, you write it as a small script — in zsh, Python, or whatever you are comfortable with — and add it as a tool of the Run program / script kind. Two things matter so that a fresh script runs at all. They are the most common reason nothing seems to happen at first:

  1. The first line says what the script runs with. It begins with ! (called a "shebang") and names the interpreter, e.g. !/bin/zsh for a shell script or #!/usr/bin/env python3 for Python.

  2. The script must be executable. You set this once, in the terminal:

    chmod +x ~/bin/my-tool.sh

    (A terminal in the current folder you get easily via right-click → Right-click  Open Terminal here.)

Miss either one and FileWorks shows an error in the panel’s status bar instead of a result.

A few more things that make scripts predictable:

  • The files arrive as a clean list. You never have to put file names in quotes yourself — spaces and special characters are already handled. {paths} on its own becomes one value per file ("$@" in the shell, sys.argv[1:] in Python).

  • The script starts in the panel’s folder. Relative paths and files your script writes land there — right where you can see them.

  • Once for all, or once per file? With once with all, the whole working set goes to a single run (you write a loop over {paths}). With once per item, FileWorks calls the tool separately for each file — you write the script for a single {path} and let FileWorks do the repeating. "Once per item" also gives you a progress bar you can cancel, and an error on one file does not take the whole batch with it.

  • Success means "finished without an error". Whether an output file is written and the run is reported as done depends on your program ending cleanly (exit code 0). In a shell script, set -e makes it bail out honestly on an error.

16.8. Example: A Small Shell Script

This tool makes a timestamped backup copy of every marked file into a Backups subfolder — handy before you try something risky. Save the text as ~/bin/fw-backup.sh:

#!/bin/zsh
# Copies each passed file into a "Backups" subfolder, timestamped.
set -e
dest="Backups"                       # relative to the working directory
mkdir -p "$dest"
stamp=$(date +%Y%m%d-%H%M%S)
for f in "$@"; do                    # "$@" are the {paths} arguments
    cp -R "$f" "$dest/${stamp}_$(basename "$f")"
done
osascript -e "display notification \"$# item(s) backed up\" with title \"{app-name}\""

And here is how you set it up:

  1. In the terminal: chmod +x ~/bin/fw-backup.sh.

  2. Under Settings  Tools add a tool, Type = Run program / script.

  3. Program = the path to the script, Arguments = {paths}, Working directory = active panel, Run = once with all.

  4. Mark a few files and run the tool.

Each run drops the copies into Backups/ and briefly shows a notification with the count. (The notification is the visible result here, because the script itself prints nothing.)

16.9. Example: A Small Python Script

The same idea in Python: write a manifest.csv into the folder, listing the marked files with name, size and modification date. Save as ~/bin/fw-manifest.py:

#!/usr/bin/env python3
# Writes a CSV overview of the passed files into the working directory.
import sys, os, csv, datetime

paths = sys.argv[1:]                  # the {paths} arguments
with open("manifest.csv", "w", newline="") as out:
    writer = csv.writer(out)
    writer.writerow(["Name", "Bytes", "Modified"])
    for p in paths:
        info = os.stat(p)
        when = datetime.datetime.fromtimestamp(info.st_mtime).isoformat(timespec="seconds")
        writer.writerow([os.path.basename(p), info.st_size, when])

Set it up as above (chmod +x ~/bin/fw-manifest.py, Program = the script, Arguments = {paths}, once with all). When it runs, manifest.csv appears in the list — the file is the result. The shebang #!/usr/bin/env python3 finds Python 3 (on macOS via Apple’s "Command Line Tools", which you are offered to install the first time).

The same pattern fits almost anything scriptable — converting images with sips, editing PDFs, git commands, uploads. Reach for {dir} or {target} when a tool should act on a folder rather than the marked files, and once per item when a program only ever takes one file at a time.

16.10. Ready-Made Recipes

Three complete tools to copy. Every setting not mentioned stays at its default.

Table 6. Recipe 1 — Pretty-print JSON (in place)

Setting

Value

Type

Run program / script

Program

/opt/homebrew/bin/jq (or wherever your jq lives)

Arguments

.

Input

Contents of the selected file

Output

Replace the source file

Run

Once per item

Available

For certain file types — json

Icon

curlybraces

Mark any number of .json files, one click, and each is rewritten formatted. The file-type filter makes sure the button only lights up for JSON; "once per item" gives you a progress bar; and a broken file is simply skipped with an error while the others go through cleanly.

Table 7. Recipe 2 — Shrink images to a width you choose

Setting

Value

Type

Run program / script

Program

/usr/bin/sips

Arguments

-Z {?Longest edge in pixels} {path} --out asciimath-small.{ext}

Run

Once per item

Available

For certain file types — jpg, jpeg, png, heic

Icon

photo

Mark thirty photos, run it, type the size once — and you get thirty -small copies next to the originals. A different size? Just run it again with another answer, nothing to change.

Table 8. Recipe 3 — Copy the paths of all marked files

Setting

Value

Type

Run shell command

Command

printf '%s\n' {paths}

Output

Copy to the clipboard

Available

When something is selected

Icon

doc.on.doc

Mark files, click, paste anywhere — one path per line. No script, no extra program.

Table 9. More ideas
Goal How

Fix Windows line endings (CRLF → LF)

tr, arguments -d '\r', input from selection, output "Replace the source file"

Generate checksums for a release

Shell: shasum -a 256 {paths} > SHA256SUMS

See what is eating space in this folder

Shell: du -sh {dir}/* | sort -h, output "Show in a window", Available "Always"

Move marked files to the other panel

Shell: mv {paths} {target}

16.11. When a Tool Is Available

A tool meant only for images should not look clickable while you have a text file marked. The Available setting decides when a tool is active:

Always — usable no matter what is marked. Right for tools that work on a folder ({dir}, {target}) or need no file at all — "git status here", "show disk usage".

When something is selected — greyed out until at least one file is marked or selected. Right for anything that mentions {path}, {paths}

For certain file types — active only when every marked file carries one of the extensions you list. Right for format-specific tools — an image shrinker, a JSON formatter.

The extension list is forgiving: jpg, png, heic, .JPG;PNG and jpg png all mean the same (comma, semicolon or space separate, the dot is optional, case does not matter).

With "For certain file types", every marked file must match, not just one. Mark twelve JPEGs and one notes.txt, and an image tool stays greyed out.

That is on purpose: if it ran anyway, it would also run over the text file — and a tool that replaces its source would destroy it. Better you fix the selection briefly than have something half go wrong.

If a button is greyed out, hovering tells you why — "Shrink images — only for: jpg, png" or "select at least one file".

The context menu applies the same filter, only more strictly: what does not fit is not shown at all. Right-click a PDF and, under Tools, you see only the tools that can do something with a PDF — and if none fit, the Tools entry is missing entirely. In the action toolbar, by contrast, the buttons stay where they are and are merely greyed out, so they don’t jump around with every new selection. In the empty area of a panel (right-click beside the files) you get the tools set to Available: Always — the ones that need no selection anyway.

Two things override every filter:

  • Inside an archive all tools are greyed out. An entry in an archive is not yet a file a program could open — copy it out first (F5), then it works.

  • If the program has gone (moved, deleted), the tool is greyed out and marked red in the settings list.

16.12. Progress, Cancelling and Errors

Every tool that waits for its program (that is, anything except "Output → Discard") appears at the bottom of the window, in the same dock as the copy and move jobs:

  • A progress card with the tool’s name. With "once per item" it counts the files and names the one currently being worked on.

  • A Cancel button. It stops the tool along with everything it started — exactly like Ctrl + C in the terminal.

  • A result: "Done", "Cancelled" or "Done, N errors".

If something went wrong, the card grows a Details … button. It shows the full output: the program’s message, the error code and — with "once per item" — which file it choked on. The short version is already on the card itself.

A cancelled run is not an error — FileWorks knows the cancel came from you and reports "Cancelled" instead of a failure. And a tool that prints endlessly is cut off after 1 MiB (with a note) instead of filling up memory.

16.13. Choosing an Icon

Tools of the "Run program / script" and "Run shell command" kinds carry an icon on their button. Click the icon field — a gallery opens, sorted by theme (files, media, network, security …). One click is enough. (A "launch app" tool simply shows the app’s icon.)

Below it, a field accepts any SF Symbol name, for the thousands not in the gallery.

16.14. Using Shortcuts from the Shortcuts App

If you have already built your workflows in the macOS Shortcuts app, there is no need to rebuild them for FileWorks. A tool of the kind Run shortcut starts an existing shortcut and passes the marked files to it as input.

Setting it up takes seconds:

  1. Create a new tool and choose Run shortcut as the type.

  2. Open the list in the Shortcut field and pick one. If the Shortcuts app uses folders, they appear here as submenus — purely a sorting aid, unrelated to the groups from Keeping Order: Tools in Groups.

  3. Done. As with any tool, you still decide whether it appears in the toolbar and when it is available.

The circular-arrow button next to the list re-reads it — handy when you have just created a new shortcut while FileWorks was already running.

Under Run you decide, as always, whether the shortcut gets all marked files at once or starts once per file. Which is right depends on the shortcut: one that combines several images into a single PDF wants them together; one that shrinks an image works better individually.

Under Output you have two choices:

  • Discard (run in background) — the normal case. The shortcut starts and FileWorks does not wait for it. Right for anything that works on its own ("add to reading list", "file away").

  • Show in a window — FileWorks waits for the shortcut and then shows what it reported. This is the one to pick while setting things up and when hunting a problem: if a shortcut seems to do nothing, this is where you see why.

The file-writing outputs of the other tool kinds ("write to a new file", "replace the source file") are deliberately absent here. A shortcut does not return its result this way — all you would get is an empty file.

The shortcut has to accept files. FileWorks always passes files — if a shortcut works with text instead (say, "speak the given text"), it receives the file and cannot do anything with it.

How to tell: in the Shortcuts app, Shortcut Details states what the shortcut expects as input. If it says "Files" or "Images", you are fine.

And if you are unsure why a shortcut does nothing: set Output to Show in a window for a moment. In background mode, errors stay invisible.

If you later rename a shortcut in the Shortcuts app, your tool simply keeps working — FileWorks remembers the internal identifier rather than the name, and picks up the new name the next time it reads the list. Only if you delete the shortcut does the editor report it in red.

16.15. Keeping Order: Tools in Groups

Over the years they add up. Ten tools are still manageable, thirty are not. So you can sort them into groups — "Image editing", "Development", "Text editors", whatever suits you.

A group comes into being simply by you assigning it: select a tool, type a name into the Group field and press . The group now exists, with the tool in it. For a second tool you don’t type the name again — the small arrow next to the field offers every group you have already used.

Tools without a group are perfectly fine. They gather under Ungrouped at the very top, and if you never assign a group, the list looks just as it always did.

In the list you can then:

  • collapse and expand a group by clicking its name,

  • drag a tool elsewhere — onto another row to slot it in there, or onto a group name to append it to that group,

  • reorder a whole group by dragging its name onto another group name.

This order is not just decoration: it also determines the order of the tools in the action toolbar and in the menus. So whatever you need daily belongs at the top.

In the menu bar and the context menu, each group becomes a submenu, with the ungrouped tools above them. In the context menu the availability check comes on top: if not a single tool in a group suits the file you clicked, the group isn’t shown at all — so you are never presented with an empty submenu.

The side action toolbar deliberately stays a flat list without groups — it is narrow, and submenus would be more travel than benefit there. Which tools end up in it is still your choice per tool, via Show in toolbar.

16.16. All Settings at a Glance

For reference — what you can set per tool:

Setting Meaning

Name

Label on the button and in the menu. Left empty, the program name (or, for shell tools, the command) steps in.

Type

One of the four kinds: Launch app with selection, Run program / script, Run shell command, Run shortcut.

Shortcut

The shortcut from the Shortcuts app to run (see Using Shortcuts from the Shortcuts App). Only for the "Run shortcut" kind.

Group

Which group the tool is filed under (see Keeping Order: Tools in Groups). Left empty, it sits under "Ungrouped".

Program / Script

The program to run. Not needed for shell commands (the shell is fixed at zsh).

Arguments / Command

The template with the Placeholders: Telling a Tool Which Files It Gets.

Working directory

Active or other panel. The tool starts in this folder — relative paths and written files land there.

Run

Once with all marked files, or once per file.

Icon

The button icon (see Choosing an Icon).

Input / Output

Where the data comes from and what happens to the result (see Transforming Files: Input and Output). Shortcuts only have Output, with two choices (see Using Shortcuts from the Shortcuts App).

Available

When the tool is clickable (see When a Tool Is Available).

Show in toolbar

Whether it gets a button in the side action toolbar (in the Tools menu it always appears anyway).

The order in the tool list (on the left of the settings, changeable by dragging) is also the order of the buttons and menu entries. Put what you need daily at the top — see Keeping Order: Tools in Groups.

17. For Power Users: Security and Internals

This section is optional deeper knowledge. For everyday use you don’t have to read it — the rule "write {path}, never "{path}"" is enough. But if you want to know exactly why it is safe and where the limits are, the explanation is here.

17.1. Why File Names Never Become Commands

File names come from the file system, not from you — and a file may perfectly legally be called $(rm -rf ~).txt. If FileWorks simply pasted such a name as text into your shell command, merely clicking a tool could cause havoc.

That is why FileWorks never pastes a value into your command as text. Each placeholder is replaced by a reference to a shell parameter ("$1", "$2", …), and the actual values are handed to the shell separately, as arguments. The shell fills them in but never looks at the result again for $(…), back-ticks and the like — so a value stays a value. Your command itself — pipes, &&, loops, redirections — stays untouched. These lines all do exactly what they look like, safely:

wc -l {paths}
grep -c foo "{path}"
echo '{name}'

That is exactly why you never quote placeholders yourself: FileWorks does it for you.

17.2. Feeding Another Language (Python, awk … in a Here-Document)

FileWorks makes the shell safer. But if you drop a value straight into the source of another language — say a Python snippet in a here-document — then a name with a quote in it could throw that language off. FileWorks cannot sanitise Python code you assemble yourself.

The fix is the same idea one level down: let the other language receive the value through its own arguments or standard input, instead of writing it into its code:

python3 - "$1" <<'EOF'      # note the QUOTED <<'EOF' and the "$1" argument
import sys
print(sys.argv[1])          # the path arrives as a value, never as code
EOF

Every placeholder is available as "$1", "$2", … in the order it appears.

17.3. Environment Variables (FW_*)

Even more convenient: the common single values are available as environment variables you can read from any language — without them ever being able to turn into code:

Variable Value

FW_PATH / FW_NAME / FW_STEM / FW_EXT

Path / name / name without extension / extension of the first marked file

FW_DIR / FW_TARGET

Folder of the active / other panel

FW_COUNT

Number of marked files

So os.environ["FW_PATH"] in Python or "$FW_DIR" in the shell both work. (Lists like "all paths" exist deliberately only as {paths}, not as a variable: a file name may contain a newline, which no single variable could separate safely.)

17.4. The Limits

An absolute guarantee would only be possible without a free shell mode, or with strong isolation of tools. FileWorks deliberately offers the free shell — and hands values to it safely. What the tool then does with them is up to the tool’s author.

A command that deliberately re-interprets its arguments turns the value back into code — and lifts the protection. This concerns constructs like:

eval "$1"
zsh -c "$1"
xargs sh -c '…'

Such patterns are the tool author’s responsibility. As long as you use placeholders simply as values ({path}, "$1", $FW_PATH) and do not explicitly run them as code, you are on the safe side.

18. Configuration

You open the settings window with + , (FileWorks  Settings …). On the left you find six sections.

config01

18.1. General

The largest section, divided into:

Appearance
  • Show hidden files — same as + + ..

  • Sort folders first — group folders ahead of files.

  • Show thumbnails — small previews in the name column.

  • List icon size — height of icon and row in the list, 16–48 pt.

  • Icon view size — tile size in the grid, 32–128 pt.

Columns

Which columns appear in the list: Extension, Size, Modified, Kind and Finder Comment. The Name column is always there.

Select by Mask

Include folders — whether the mask field ( + F) also marks matching folders, not just files.

Selection & Quick Look

Both Quick Look and Mark item sit on the Space bar. Here you build the modifier for each, next to a fixed Space key — with four checkboxes (, , , ). That way you put a command on a combination no other program uses. The two can never share the same combination: choose one that is already taken and they simply swap. (Some combinations such as + Space macOS keeps for itself.) The defaults are plain Space for the preview and + Space for marking.

config01 1

Startup

Restore last folders on launch — reopen the previous session’s folders (off: both panels start in Home).

Deleting
  • Confirm before deleting — show a prompt.

  • Move items to the Trash — off: items are deleted permanently and cannot be restored.

Archives

Open archives as folders — off: archives open with their default app instead of being browsable.

Terminal

The app for Open Terminal here — the system Terminal by default, or one of your choice (e.g. iTerm).

18.2. Colours

Rules that tint files by their extension. Each rule has a name, a colour, a list of extensions and a switch. Drag to reorder — the first matching rule wins. FileWorks comes with sensible defaults (Images, Videos, Audio, Archives, Documents, Code).

config02

18.3. Favorites

The folders in the Favorites section of the sidebar. With the + button you add folders, here you reorder or remove them. Missing folders are shown dimmed.

config03

18.4. Editing

The apps for Edit (F3) — see Editing and Opening Files. With the + button you add an app and type the extensions it handles (comma-separated). An empty list means: the app matches every file.

config04

18.5. Tools

The editor for your own tools — see Custom Tools. On the left the list of your tools, arranged by group (drag to reorder and regroup, + and to add and remove); on the right the editor for the selected one. Which fields the editor shows depends on the Type: a "launch app with selection" tool needs only a handful of entries, while a script tool additionally gets arguments, input and output, and the placeholder overview.

config05

18.6. Network

The remembered network servers from the sidebar. Passwords are never stored here — that is the macOS keychain’s job.

config06

19. Keyboard Shortcuts

FileWorks can be driven entirely from the keyboard. A full, always-current overview is built into the app: Help  Keyboard Shortcuts. The most important ones:

Table 10. Panels & Tabs

Action

Shortcut

New Tab

+ T

Close Tab

+ W

Next / Previous Tab

+ / + +

Switch Panel

Swap Panels

+ U

Show / Hide Second Panel

+ + 2

Table 11. Navigation

Action

Shortcut

Back / Forward

+ or

Enclosing Folder

+

Home

+ + H

Go to Folder …

+ + G

Favorites and volumes (left / right)

+ 1 / + 2

Connect to Server …

+ K

Table 12. Selection

Action

Shortcut

Select All

+ A

Select None

esc

Extend Selection (list)

+ or

Toggle Mark

+ Space (or -click)

Invert Selection

+ + I

Smart Select

+ + S

Smart Deselect

+ + + S

Select by Mask

+ F

Quick Filter

+ + F

Find Files …

+ + F

Table 13. Files

Action

Shortcut

Rename

F2 or + R

Edit

F3 or + + E

Copy (to other panel / folder)

F5 or + + C

Move (to other panel / folder)

F6 or + + M

New Folder

F7 or + + N

New Folder with Selection

+ + N

Move to Trash

F8 or +

Multi-Rename …

+ + R

Add to Drop Shelf

+ + D

Table 14. Clipboard & View

Action

Shortcut

Copy / Paste

+ C / + V

Paste (Move)

+ + V

List / Icon view

+ + 1 / + + 2

Show / Hide Sidebar

+ + S

Show / Hide File Info

+ + I

Show / Hide Hidden Files

+ + .

Refresh

+ + R

Cycle Toolbar Mode

+ + B

Quick Look

Space

On notebooks the function keys (F1F8) sometimes need the fn key — or you enable "Use F1, F2, etc. as standard function keys" in System Settings  Keyboard.

20. Tips & Tricks

  • Mark first, then act. Mark a batch — with + Space as you go, with -click or a + F mask like *.tmp — and then F8 to delete it all at once. The marks survive a stray click.

  • Incremental backup. When you copy a folder over an older copy, choose Replace All Older in the conflict dialog — then only newer files are updated and the rest are merged.

  • Compare two folders. Open both side by side and sort them the same way — in the dual-pane layout the differences jump right out.

  • Collect across folders. As you browse, drop files on the shelf (or + + D) and drag them all out together later — with Keep items after dragging out for several destinations.

  • Neighbour hop. The small chevron between two folders in the path bar jumps straight into a neighbouring folder.

  • Refresh comments, tags and sizes. + + R re-reads externally changed Finder comments and tags and recomputes package sizes.

  • One hand on the keyboard. switches the panel, F5/F6 transfer, Space shows the preview — a whole workflow without the mouse.

  • Teach FileWorks your own moves. Anything you keep typing in the terminal is one + + B button away — a one-liner takes a minute to set up (see Custom Tools).

21. Supporting FileWorks

FileWorks is free. If you would like to support its development, take a look at Start, another app from the same developer, available on the App Store and on Setapp. Your purchase supports the ongoing development of both apps.

You can open this note any time from Help  Support FileWorks ….

22. The About Window

FileWorks  About FileWorks shows version and build — and next to them two buttons that save you a detour: Keyboard Shortcuts opens the overview of all key assignments, User Manual this document. You will find both in the Help menu as well; in the About window they simply sit where you end up anyway when looking something up.

23. Notes and Troubleshooting

  • Full disk access. FileWorks runs outside the macOS sandbox — a file manager needs full access to the file system. macOS asks the first time you touch Desktop, Documents or Downloads (the usual prompt). Grant it so FileWorks can work with those folders.

  • Archives unavailable. If the system’s libarchive is missing, browsing, packing and verifying are off, and archives open with their default app; everything else runs normally.

  • Merge on the same drive. When moving on the same drive (the fast rename path), the Merge option is not offered for folder conflicts.

  • Nothing happens on F5/F8. Make sure a file panel has focus (click into the list) and — on a notebook — that the function keys reach the app (see the note under Keyboard Shortcuts).

The trademarks and product names mentioned in this manual belong to their respective owners and are hereby acknowledged. The mention of products is solely for informational purposes and does not constitute advertising. Similarly, no guarantee is provided regarding the selection, performance, or suitability of these products.

24.1. Privacy & Security Information

We developed FileWorks as a commercial application designed to provide a seamless, ready-to-use experience right out of the box. Our focus lies on both functionality and data protection.

FileWorks is built with your privacy as a top priority. Your personal data and information remain under your control at all times:

  • Local Storage Only: All your data is stored exclusively on your local device

  • No Data Collection: We do not collect, transmit, or share any of your data with third parties

  • No Cloud Services: The app operates completely offline, ensuring your information stays on your machine

24.2. Security Features

  • Apple Notarization: Verified and notarized by Apple to ensure malware-free operation

24.3. Disclaimer and Limitation of Liability

While we strive to provide a secure and reliable application, please note:

  1. No Warranty: The software is provided "as is" without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose.

  2. Limitation of Liability: In no event shall the authors, copyright holders, or developers be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.

  3. User Responsibility:

    • You are responsible for maintaining appropriate backups of your data

    • You use the application at your own risk

    • You are responsible for reviewing and complying with all applicable local laws and regulations

  4. Technical Issues: We cannot guarantee that:

    • The software will be error-free or uninterrupted

    • Any errors in the software will be corrected

    • The software will be compatible with future operating system updates

  5. Data Security: While we implement reasonable security measures, we cannot guarantee absolute security of your data against unauthorized access or system failures.

By using FileWorks, you acknowledge and agree to these terms and limitations. If you do not agree with these terms, please do not use the software.