Working with the Finder Selection

In Keyboard Maestro, you work with the Finder Selection by using the For Each action to iterate over the selected files. From there, you can do whatever you would like with the files using the various file actions, or by processing with a script or other means. There is a smart action in the acton selector for For Each Path in the Finder Selection, which is simply a For Each action, preset to iterate through the Finder Selection collection. You can put whatever actions you like within that action.

To change the Finder Tags, you would use:

To move the files to the Documents folder, you would do this:

Note the consistency between them. And note that you could do both in a single For Each action if you wanted (you would have to ensure the Move was done last of course, as that will change the path to the file).

To rename the selected files, you would do this:

You can pass each file to a shell script using something like this:


Sadly, KM's inability to work with Path Finder severely limits the functionality here. I was just going to implement this, but remembered that it won't work. As I use Path Finder as my "Finder" of choice, it's not feasible to open Finder, navigate to the necessary folder, and then start the workflow from there. There's GOT to be a better way.

You can use “The files in directory” rather than “The Finder’s selection” in the “For Each” action, and you can pass the directory to use to the “For Each” action via a variable.

This is not KM's inability. It is Path Finder's inability to play nice with other apps.

The Finder is highly AppleScriptable if a bit creaky and buggy. Path Finder on the other hand is NOT very scriptable. Please complain to Cocoatech about this. Unless users ask for features they don't get much attention. Dragon shoots me down every time I ask for enhanced AppleScript support, because not enough people want it.

Now. Did I not post about how to work with the PF selection? Here's how to get it into KM.

tell application "Path Finder"
   set selItemList to selection
   repeat with i in selItemList
      set contents of i to quoted form of (get POSIX path of (contents of i))
   end repeat
end tell
set AppleScript's text item delimiters to linefeed
tell application "Keyboard Maestro Engine"
      set value of variable "pathList" to (selItemList as text)
   on error
      make new variable with properties {name:"pathList", value:(selItemList as text)}
   end try
   value of variable "pathList"
end tell

Quoted form is necessary for the shell, but I'm not sure about KM and don't have time to test right now.

You can get the path of the active pane.

tell application "Path Finder"
   path of (target of finder window 1)
end tell

You can set the path of the active pane.

set _alias to (path to home folder)

tell application "Path Finder"
   open _alias
end tell

So. While Path Finder's AppleScript support is very crude you can still accomplish a fair amount.

Mix and match AppleScript and Keyboard Maestro, and the possibilities get pretty large.



Thank you - you are right, you did post to me on another issue about working with the PF selection, and I forgot about it. I have taken all your points into consideration, and will certainly contact CocoaTech about that. Please forgive my brusqueness (if that is anywhere near the right way to say what my attitude must have reflected.) I will work on this and see if I can’t get my needs met with this guidance.

OK, at the risk of upsetting you, I have to ask for more help here. Please understand that I am not an IT guy. I am a Customs broker, with limited time to learn this stuff, and I am trying to automate much of what I do. So please understand that many of these concepts are WAY over my head. Example: I do not understand the purpose or application of the "get" and "set" items you gave (I understand what the "get" does, but I don't understand why it's part of this conversation. I must be missing something.…)

That being said, I tried using the script you gave, and all I get is a "donk" sound when I try to run the macro in PF. I've tried numerous variations of the "For Each Item" arrangement, as well as the enclosed screenshot. I'm not asking for 100% answers - I do appreciate learning this stuff, but clearly I need a bit more handholding that you guys may actually want to give. Where am I going wrong here?

(I also sent an email to CocoaTech requesting better AS support.)

Hey Bob,

We have a users list for the express purpose of giving and receiving help for Keyboard Maestro, so asking for same isn't going to upset anyone.

KM is a very complex utility, and while using it in a basic way is relatively easy the advanced stuff takes a little (or a lot of) getting used to.

The best way to get help with a project is to clearly and completely state what the project is. People tend to waste a lot of time by posting questions about little bits and pieces of their task several times before finally getting to the heart of the matter. That's not a bad thing when a person is trying to learn how to use KM, but if they're actually trying to get something working it's significantly more effective to provide the whole picture.

Now. Let's get back to your problem.

You've made a common mistake (that I've made myself) in trying to apply a single file action to a list of files. You have to use a collection (Peter's euphemism for a loop) to iterate through the list and apply your action to each file.

You can see in the appended graphic that I've changed the AppleScript a bit and let KM pipe the result directly into one of its variables, and I've added a little error-checking.

I had time to test today, and as I hoped KM didn't need the path strings to be quoted. (Yea!)

Note that this macro replaces any tag already on the selected files, however there are other options in the Set File Attribute action for adding, removing, and toggling tags.

Download the macro and give it a try. It should provide you with a template for doing other things.

Let me know if you have any problems.


Path Finder » Set Tags of Selected Items to Red.kmmacros (5.7 KB)


Chris, thank you very much! That works exactly as I wanted!

You’re right about several things - KM is complex once you go beyond simply Hot Key assignments and stuff like that. To be honest, it’s why I gave up on Macro Express over on Windows years ago - the stuff I wanted to accomplish was to complex for my understanding, and I didn’t have the time to invest in it. As it is now, time is still limited, but getting better as I learn more about my Mac, and what I can do with AS, Hazel, Automator and KM, and even some stuff like RegularExpressions (just learned about those last week). It’s been a stiff learning curve, but I want to get the absolute most out of this computer. I still don’t understand a lot of concepts (for example, why the KM syntax of a filename variable is bracketed with percent signs).

I’m grateful for your help; I also completely understand what you’re saying about not being clear enough when outlining what I’m trying to accomplish. That’s the result of 25 years as a Customs broker, and learning that most people don’t pay attention to what you are saying anyway, and you have to break it down into bite size chunks or they won’t do what you need them to do for their own benefit! So, I’ve got to change my way of thinking as I delve deeper into this stuff. (To be honest though, I see a lot of arrogant jerks whose best contribution is “why don’t you just use the menu?”, and that does not inspire one to lay it all out…not saying that about KM users, just in general on many forums).

It’s basically a template system.

Imagine you want to insert the text: “Hello Peter, how are you this fine Tuesday?”. That’s easy, and everything is fine.

But now imagine you want that to be general, not just specific to “Peter”, not just specific to “Tuesday”. So what you want to say is something like “Hello NAME, how are you this fine DOW?”. Now what you have is a template system. There are a zillion ways of marking and specifying NAME and DOW, but in Keyboard Maestro it might look something like “Hello %Variable%Name%, how are you this fine %ICUDateTime%eeee%?”. The percent signs delimit the replacement text (and if you want to use a plain percent sign, you use %%).

What Peter left out his explanation is that all variables in Keyboard Maestro are pure text and all input and output as well.

So when you use a variable you end up with a text-token representation of the variable within a larger text body. In order to replace a variable-token with its value you have to be able to find it, and Peter’s scheme for defining a variable-token is:


%Variable% is a fixed value that explicitly tells you the following text will be a variable name - then there is the variable name - and the end is of course another percent sign.

This scheme makes it very simple to find and replace the token within the context of where it is used.

Just think of find/replace within a word processor or text editor. You have to be able to define what you want to find and replace.



This explanation of variables is quite brilliant. I can now translate this

%Variable%your-variable-name% into "my understanding".

There are a lot of key concepts, e.g tokens that I do not understand. Any chance of explaining?

%Variable% - what comes next is going to be the name of a variable, a box, a container, a jamjar,
your-variable-name% but there are lots of boxes, containers, jamjars so the one you are looking for is called your-variable-name%

Inside you will find what you are looking for or need to proceed. OK.



Here is the problem: Lots of things in Keyboard Maestro let you specify plain text. For example, you can paste in text with the Insert Text by Pasting action, you can append text to a file, you can set a Safari field to text, you can press a button by name, you can speak text, etc.

So all those places let you type the text in to a field. And they are all useful as is.

But they would all be more useful if they could contain some information that changes depending on the circumstances. For example, the current date or time, or the text in the clipboard, or the text in a variable, or a random number, or a hundred other things.

So how do you shoehorn in context sensitive changing information into the plain text that you have written? And the answer is a template system, just like those used for Mail Merge or Form Letters, or many other cases with the same issue - some static text with some extra variable pieces mixed in.

So with any template system you need a way to specify the varying stuff. In Keyboard Maestro, that way is with tokens surrounded by percent characters.

There are many, many Tokens available in Keyboard Maestro, but they are all used in more or less the same way. For example:

Insert Text by Typing "The Clipboard is %CurrentClipboard%"
Append Text to File “The Current Date is %LongDate%”

Some more complex tokens need a parameter, so they may have three percent characters. For example:

Speak Text "The variable contains %Variable%Var Name%"
Log Message “Three days from now is %ICUDateTimePlus%3%Days% EEE, MMM d, yyyy%”

I hope that is clear now.

1 Like

Hey Michael,

When I don’t understand words my first stop is the dictionary. Of course that can be confusing when words have many meanings and contexts, but it usually gives me some perspective.

Let’s look at definition 3 of token in Merriam-Webster’s Unabridged dictionary:

a : something (such as an act, gesture, or object) that serves as a sign or signification : mark, emblem

<a white flag is a token of surrender>
<waved her handkerchief as a token of recognition>

So – we see that a token often is a symbol for something else.

What’s a subway token? It’s a symbolic representation of monetary currency that can only be used for one purpose – to pay for the subway.

What does \d mean in a regular expression?

\d is a token for [0-9]

[0-9] is a token that means any digit from zero through 9.