After Reading the Relevant KBM Wiki Page I'm Still Not Clear on What a Token Is

I read the KBM Wiki on variables and it is quite clear in my mind now. Text, numeric, array variables etc
I also read the definition of tokens, but am still not clear what tokens are.
thank you

The KM Wiki defines it likes this:

Tokens in Keyboard Maestro represent placeholders for information about a specific object.

If this definition is not useful for you (I don’t find it too bad) and you are familiar with the concept of variables, then maybe it helps to see a token as a special kind of variable. The “special” things are:

  • You cannot change the name of a token

  • The value (content) of the token is always the same, example: %Return%,
    or it always refers to the same object, example %TriggerValue%, %SystemClipboard%, (the value can be different here)

Not sure, if it is clearer now…

1 Like

Thank you Tom.
Do I understand correctly that I can invent any name for a variable, such as %Tom% but tokens are 'hardwired' and defined by either the KBM software or intrinsic to the Mac OS ?

Yes. The correct form for a variable would be %Variable%Tom%, though in the form %Tom% probably it will work also (at least if there isn’t a name clash with an existing token).

Yes, I think, one could say that KM tokens are “hardwired” by KM (at least the name).

1 Like

You can also “transfer” (store) any token to a variable of your choice:

[demo] Token to Variable.kmmacros (2.8 KB)


If you are going to use the token value in your macro, it is always a good idea to “transfer” (store) it to a variable before doing so. Otherwise bad things could happen, for example the token value could change while your macro is still working with it.

If you are going to process (in the sense of ‘possibly changing’) the token value, it is necessary to store it to a variable, since you cannot change the value of a token, for example by calculation actions.

1 Like

thank you very much Tom, I have to read your post a few times to digest its content.

1 Like

Just ask, if something is unclear or my wording is off or incomprehensible.

1 Like

To expand on the second point:

Quoting myself:

If you are going to process (in the sense of ‘possibly changing’) the token value, it is necessary to store it to a variable, since you cannot change the value of a token, for example by calculation [or replacing] actions.

Let’s take the %FrontBrowser% token. As shown above it returns your current front browser. In the example “Safari Technology Preview”.

Now let’s say we want to transform the value (Safari Technology Preview) to something different, for example by replacing “Technology Preview” by “TP”.

First attempt: Staying with the token – unsuccessful:


The input of the action is the token and we are trying to save the modified value back to the token. You notice that the option to save the result to the source (= the token) is dimmed (= not possible). It’s a token and we cannot change it. [1]

Second attempt: Saving the modified value of the token to a (new) variable – successful:


When attempting to save the modified value to a variable (or any other that is not the source (= the token)), it is not dimmed. We can do that, because variables can de declared and modified at will:


Now we have modified the token value and declared a new variable with that modified value.

Third attempt: Saving the token to a variable first and then changing the value of the variable – successful:


Here we store the value of the token to a variable (name of your choice) beforehand. Then we modify the variable (which now holds the value of the token).

We can modify the value of the variable and save the modified value back to source (= to the variable). This was not possible with attempt 1, where we also tried to save back to the source. (A token can not be modified, a variable can.)

1: I know that the first-level reason we cannot save back is that the input is text. But, pragmatically, I think this is not relevant here.


thank you very much for an outstanding explanation. It is clear now.

@Tom knows what he is doing but explaining this particular part of KM (and of other IT things that use the similar terminology) is really hard obviously: I think it is a huge step conceptually, if you will, from most automation. I am not sure you don't really need a background some of us just don't have. I am writing this to kind of feel around for something that I might get and need.

David Sparks helped a bit on his Field Guide for me, a little bit. @JMichaelTX tried hard directly with me but failed, the wiki didn't help really and I still don't really get Variables in KM. Tokens are, by the definition given, a kind of variable as Tom says correctly: but then Tom went on to talk about tokens having 'values' which don't change and/or 'objects'. a variable with a value that doesn't change is not a variable by definition in my field.

So I still can't use variables properly: I am quite happy to accept the limitations are in me by the way. Sparks, Peter Lewis, @JMichaelTX and others have failed and they are all expert and pretty good teachers: Michael would have carried on explaining to me for a long time I think, I stopped because I felt I just wasn't clicking on to something. David Sparks also uses the 'container' metaphor. Which, though it is the one I used to teach the concept in Logic myself, if not outright wrong, misleading. Even in math a variable doesn't take 'anything' as we say when short of time, as a value, it doesn't take apples and pears for example. YES I KNOW! that is obvious... but...

Variables in math are notoriously tricky as it happens. I know math to a high level but am one of the few now who never learnt to code as such or did any Computer Science: all I know in IT is as a 'power user', as a secondary thing you might say, I wonder sometimes if I have some preconception from my background that is tripping me up all the time on this. Others outside this community have failed with me too: I suspect there is something specific to KM that I need to cotton on to. I am no wiser after reading this thread than I was before and Tom tried hard and shared his valuable time.

Thanks for the effort here @Tom. I will keep working through your stuff on this thread, and see if I can click on to something that I obviously need to grasp. I am starting to think that it would be better to change the whole terminology in some way?

I have to admit, my explanations were tailored specifically to @ronald, since I have the feeling I more or less understand where he is in his understanding of KM concepts (we had many conversations), though sometimes he still manages to surprise me :wink: (the one or the other direction)

I have no clue of maths. I guess it would be asking too much to explain me the basic concepts of variables in maths, but maybe the main differences? (I think KM’s concept of variables is pretty similar to the concept in other languages like Perl, Ruby, Swift, etc., just to name a few where I have a minimum of idea. (Of course the way how variables are treated/processed is different in each language. But we’re speaking of the concept here.)

That’s what I wanted to express with “seeing tokens as ‘special’ variables”. (I knew this can lead to confusion.)

But BTW, independently of KM, many variables you use never change their value. (Well, in the case you don’t expect a variable to not change the value, I would rather declare it as constant. But I think this differentiation would just add an unnecessary complication.)

Edit: PS:

And I even considered to explain tokens as something like constants. But I thought this would just be too wrong (they aren’t), and not helpful in the context (introducing a new term).

1 Like

How that? KM’s “variable” and “token” terminology you mean?

1 Like

Thanks, I will come back to you if I get any further with this on KM: I am not sure if I need to, since to date I have been able to just get macros using variables from other folk, I have an useful renaming one for example. I have no idea how it works though, I tried to work through it. I need to do some work myself on trying to undertand it.

I actually think the range and meaning of the terminology has drifted from its origins in math and logic to the usage in computer languages. Which is fine by the way and how it goes, that is interesting to me independently of IT by the way: I get a lot of interesting material on this site. In fact the use of another term for variables that don't change would, in my view then, be very welcome actually to avoid confusion.
I don't like to overstay my welcome though and take up too much time. I really appreciate how generous, you and many others are in that way here. I hope you don't mind my kind of approach? If not I will continue to engage with you if that is ok.

Yes. I am just entertaining an idea. Since I don't really understand it I don't feel I can take a strong position on terminology. I also see that meaning has drifted from its origins and that is how it always is by the way; so I don't take that as a criticism as such, just something to be aware of. Sometimes, in English notoriously for some reason, words often drift, in language generally, into their opposites, sometimes both meanings are retained. "Literally" being a recent one, 'cleave' and 'bolt' are others. I see no reason why 'variable' might not, in some contexts, come to mean 'constant.

Not an expert here, but I think this is plausible.

What is the exact “thing” you don’t grasp with KM variables? Sorry for the stupid question, but maybe this concrete piece of info could be helpful. If you can nail it down. (As said, I’m clueless of maths variables.)

1 Like

2 posts were split to a new topic: TIP: Understanding KM Tokens

@Tom and @tudor_eynon, the subject of KM "Variables" has already been discussed at length here:

If either of you, or anyone, really feel the need to discuss further, then create a new topic on "KM Variables" by clicking on the link icon of that post.

This thread is about Tokens. Let's keep on topic, please.


Technically you are right (except the mentioned tokens like %Return%, but this doesn’t matter). I just did not want to introduce that term here, because I feared it will lead to more confusion.

As said my answer was tailored to @ronald, and I had the impression he was familiar with the concept of variables. That’s why I started there. (See the OP.)

But, as said, technically you are right, most of them work as functions, and the value can change at any time, which I mentioned as serious caveat here if one is using the the token throughout the macro.

I would add the explanation as function to the wiki, it is certainly useful and will help people understand.

Since tokens and variables get sometimes confused (see the OP!), and they can be used in a similar way under certain conditions, I would opt to not split this thread based on whether a post is more about variables or more about tokens.

The thread started about the differentiation of variables and tokens.

1 Like