Beginning before the beginning: the basics of the building blocks?

Hi KM Community,
I’ve been watching videos and trying to create my own macros but come up against deeper ignorance than getting to know this program. How do I know when a variable is called for vs something else? How do I know what the capabilities of each action and type of action are? Of course I should experiment, but my starting point is so basic that the outcome of the experiments is that whatever I try doesn’t work. Point taken but with so many possibilities, it’s hard to know how to be systematic in a way that I learn from my mistakes.

So can anyone recommend a starting point for understanding the building blocks themsrlves and what order they need to be entered so that they work?

Just FYI, I can’t use the record feature because I rely on a zoomed screen, which means I’m panning around for where I need to do something after hitting record, which of course means searching is captured too! But really I just want to understand the basics of the language at the root of KM so I can get to the basics of knowing trial and error.

Hopefully this question is so “dumb” that it isn’t!


In my opinion, reading about how software works is so boring it defies success. It’s far better to have actual projects and goals and seek help along the way.

Well, you’ve already made some starts so …

If you post some of your experiments (there’s nothing wrong with that) and also explain what your attempt was trying to produce, the community can help your revise your attempts in the direction of success. Remember – you define success, we don’t – if the macro does what you want, you succeed.

Nothing here is ‘dumb’ :slight_smile:


Hey @Pommette,

Read the Quick Start:

It’s not long and will give you basic vocabulary you need to proceed.

Don’t forget theres a wiki:

Keyboard Maestro’s various goodies are explained in some detail there.

Sub-items in these menus have help attached when you hold down the Option-key:

Edit Menu:
     Insert Action
     Insert Token
     Insert Function

The Actions panel you bring up by hitting Cmd-K will let you Option-Double-Click to get help for the given item.

When I first downloaded Keyboard Maestro back in early 2004 or so, the first thing I did was to look through all the macros that came with it.

I then disabled ALL of them.

Then I looked for ones I might use and reenabled them one at a time.

I also deconstructed them to see how they worked.

I’d make a duplicate of a macro and disable bits and run it – reenable bits – and run it – to see how it worked.

Be patient with yourself. Starting from scratch with Keyboard Maestro takes study and play and time.

If you want help with something ask on the Forum – DON’T bang your head against the wall for hours…

If you can’t figure out something in 15-30 minutes it’s time to ask for help.



Welcome to Keyboard Maestro (KM)!

You'll generally find a friendly bunch of folks here, including the Keyboard Maestro developer, @peternlewis. So feel free to ask any KM-related question.

Let me start with this premise: You can automate, using KM, almost anything that you, as a user, can manually do. There might be a few edge cases that you can't automate, but in general KM is a very broad, and deep, automation tool.

So, as @korm mentioned, the best way to get started is to have a specific project, a specific workflow, that you want to automate. It's usually best to start with something simple, but repetitive.

With that in mind, you do need to first learn the KM app a bit, things like how to create a macro, add/delete/change Actions, and set macro triggers. Here are some recommended steps to get started:

###Getting Started with Keyboard Maestro
(don't skip the first two steps -- they are essential to getting you started quickly.)

  1. Read the Quick Start.
  • This is essential to become familiar with KM terminology
  • Do the tutorial (Help ➤ Tutorial) in the KM Editor.
    • Gives you a live walkthrough of creating a macro in the KM Editor
  • Review/Browse the Available Macro Actions
  • For Help with an Action in your Macro, click on the gear icon at the top right of the Action, and select "Help"
  • Search the Keyboard Maestro Wiki for detailed help.
  • Start small, and grow your macros organically.
  • Be prepared for some trial and error in the beginning.
  • Make good use of this Keyboard Maestro Forum
    • Search for existing macros
    • Post your questions/issues if you get stuck

###Example Macros
Finally most of us learn best by example. You can find a list of example macros by doing this forum search:

###Forum Search

You could then add keywords to filter the search, like:
tags:examples finder
to see examples about the Mac Finder app.

###Macros Posted by Users
We also have a great collection of macros that have been uploaded by the user community. To see this list, click on the Macro Library forum category.

Then there is the Best Macro List that you can browse.

Good luck, and please feel free to ask any questions.


Lots of great suggestions here, but I'm going to focus on this one:

As @JMichaelTX says, Keyboard Maestro is a very broad and deep tool. In this respect, it's like any other tool, say a chisel or a soldering iron.

If you were starting with a chisel, you'd start by doing something like this:

You would not try to start with something like this:

The same is true for Keyboard Maestro, and I suspect too may folks try to do something complicated before learning how to do something simple. Probably a lot of that is simply not realizing which things are complicate and which things are simple because the way computers work and the way brains work are very different.

Regardless, start small and simple and then grow your macros organically. If you have a repetitive task, just automate the first step of it. Then maybe another step, and another step, each with their own macros. Then later think about how you could combine them into a single macro that does the whole thing.


Thank you Peter - I’m honored and touched that the Big Cheese himself would respond, and with images no less! Agreed that it’s hard to know what’s simple vs what’s complicated but I’ll follow your and others’ sage advice.

As I said somewhere I’m struggling with sorting out some of the building blocks themsrlves - one block at a time. Then it’s a matter of what follows logically and learning to think like KM as someone who is definitely a non-linear thinker.

It’s fun so thank you.–P

You might start by just writing down the manual steps you take to accomplish your workflow. You could even put this text in the Comment Action of a macro.

Then, you should be able to identify blocks of steps that are closely related, that could be performed independent of the other blocks.
Try writing a very short Macro to automate one of these blocks. Test that Macro until you have it working as you want.

Then, using the output of that first macro, write another macro for the next block of steps. When that is working, you could combine these macros in at least two ways:

  1. Create a 3rd macro, and copy the actions from each Macro into it.
  2. Create a 3rd macro that calls each of the other two macros, using the Execute a Macro action (KM Wiki).

Continue this process until you have automated your complete workflow.


Sometimes I still do this for complex workflows. Drawing it out on a big sheet of paper sometimes helps me figure it out.

1 Like

No it isn’t dumb. I actually uninstalled KM but have now re installed KM I was so frustrated. Basically after listening to Sol Soghasian on Mac Power Users explain briefly what a variable is in this context. His idea of "and’ rather than either or was really helpful too. I use textexpander and Hazel and thought that was enough but this tool grows on you.

I reply though because of what you say about VARIABLES. I worked hard on this and there is something opaque about the explanations on this. I don’t know what it is or how to resolve it.

The experts, really helpful, don’t seem to be able to get down to beginner level and I think ‘know’ stuff they don’t ‘know’ they know! :grinning: If that makes sense. I still can’t really say I have a handle on variables here. I wish I did. I do use them too, but I don’t really understand what I am doing. I think I understand the general meaning of variable. In fact I know I do but on KM something remains obscure and opaque. Peter tried to explain it to me and others have and do on this site and the wiki…


Well, I’ll give a shot at explaining Variables (computer science). But please read this Wikipedia article first. I think it is pretty good.

With the caveat that I’ve been immersed in the computer world, and using variables, since I was a freshman in college (~ 48 years ago), I’ll try to give a layman’s definition of “variable”.

A variable is simply a storage location where you can store the value of something, and then refer to that location later by the variable name.

For example, if I state:
x = 5
then I have stored the value 5 in the variable x.

Let’s take some real-world analogies:

  1. Your Physical Post Office Mail box
  • In this case the “Mail Box” is the variable
  • It can be set by either the postman, or by you:
    • The postman can put mail into the Mail Box. Let’s say he/she puts one letter from Apple in your mail box.
    • So this is like stating:
      Mail Box = Letter from Apple
    • so the value of “Mail Box” is “Letter from Apple”
    • The “Mail Box” variable will remain the same until someone changes it.
    • You could remove the Letter from Apple, and then the value would be empty
    • empty can be represented in various ways:
      • "" – (two quotes with nothing between them) means an empty string.
      • null – some languages set a new variable to null when it has never been assigned a value.
      • To set a KM Variable to empty just use a Set Variable to Text Action, and leave the value field empty (blank). Do NOT enter the two quotes.
  • You can set (change) the value of “Mail Box” by either:
    • Removing the mail (set to empty)
    • Replace the mail from the postman with an outgoing letter. This would set “Mail Box” to “Letter to John” (or whatever).

Your “Mail Box” is very much like a KM Variable, in that it persists day-in and day-out until/if you decide to physically remove it. At any point in time, you may get the value of “Mail Box” by going to it and opening it. Getting it does NOT change the value of it. One you set a KM Variable (in either a Macro or in the Variables Preferences pane), it remains with that value, available to all Macros, until you change it in another Macro (or Preferences). To remove a KM Variable, set it to “%Delete%”.

In KM, this would be like using Display Text action (KM Wiki) to view the value of a KM Variable.

Well, I hope this helps. Please let me know either way. :wink:


If you are looking for a variable, it is because you created it earlier in a macro, or in another macro entirely.

I understand your confusion with tokens vs variables. The terminology can be clunky at times. Tokens are built-in tools with a known behavior like %ShortDate% etc. Variables are things you create (and they may contain tokens) and to be used later.

For example:
Example Macro.kmmacros (1.9 KB)

The first action creates the browsingHistory variable and uses the %ChromeTitle%
%ChromeURL%, and %ShortDate% tokens. The second action uses the browsingHistory variable to insert that info by pasting, like so:

I am browsing Keyboard Maestro topic “Beginning before the beginning: the basics of the building blocks? - Questions & Suggestions - Keyboard Maestro Discourse” on April 11, 2017.

The third action removes the browsingHistory variable by setting it's value to %Delete%

Exactly, that is the perfect time for a variable.

1 Like

There is a huge difference:

  • Variable -- a storage location that YOU can set and get. They don't exist until you create one, typically using the Set Variable to Text action (KM Wiki).
  • Token -- an identifier that always returns the value same attribute of some object.
  • An object is almost anything on your screen, like a window, a browser page_, etc
  • An attribute is some descriptive property, like size, length, color, URL, Page Title, etc.
  • In many ways, a token is like a function.
  • See Tokens (KM Wiki) for a complete list.
  • For example, I'm going to set the KM Variable "MY Web Page" to the current URL of the active window/tab in chrome:

Here is a short (< 2 min) video that shows how I created that:


Thanks for this. As with so much in my relation to KM, truly grasping what’s going on is still beyond my reach (I’m a humanist :slight_smile: yet close enough that I want to get it. Your mailbox analogy is good; it would help if you could extend the analogy above and beyond to situate where KM is. Is it the house the mailbox is in front of? And if the mailbox is the variable itself, what are the letters inside? I’m not trying to be cute or difficult: I’m really trying to understand how the overall structure works. FWIW, I’m pretty sure I understand the basic set-up of KM, with triggers and actions. But there are sub-pieces in there, within actions where values and conditions come up. Obviously, the overarching problem is my lack of programming knowledge. That said, I sense KM builds a bridge. I just need to learn and experiment, which is actually fun! So thanks to you and everyone on this thread.

KM is, in effect, just another programming language, like AppleScript, JavaScript, Swift, C++, etc.

All of these languages can model the real world in software, as does KM.

The KM Variables all BELONG to Keyboard Maestro. You use KM to set and get these Variables.

Yes, "mailbox" IS the variable.
The letters inside it are the VALUE of the variable "mailbox"
In the case of KM, the ONLY variable type it supports is "text".
So, you could model these letters using some identifier, like the "From" of each letter, and enter each as a line in a KM variable like this:

John Jones
Mary Smith

Here's the setup in a KM Action "Set Variable to Text"

May I suggest that you not struggle too long with concepts. Just dive in the KM water and start swimming! :wink:
I think you will find that by actually creating and testing KM Macros most of this will become clear to you fairly quickly.

It is human nature that we learn by trial and error. :smile:

1 Like

Thanks @JMichaelTX! So I dove in and created two useful macros, each probably longer than what folks are recommending for beginners, but wow! I automated two tasks that have been driving me batty for over a year, and the victory is sweet. Both relied primarily on typing keystrokes. So more to discover! Thanks for your encouragement and information.


Isn’t it great? Any time you find yourself doing something mundane, tedious, boring, etc., that is a task you should automate.

My favorite tasks to address are anxiety-inducing tasks. I have several monthly tasks for work (scheduling, tax prep, etc.) that are no-difficulty, short tasks (under 20min each), but have a high cost for failure. I gain little time by automating them, but the peace of mind from knowing they’re done right is more than worth the time invested in developing their macros.


I do this often. For complex processes, I map them using the stellar little app, inShort (I’m just a satisfied customer and a huge fan of what the developer has done here, which I found — not coming from any discipline that touched on dependent processes — educational to the point of revelatory).


Wow! A very impressive tool for process/project planning and management. I could really have used a tool like this a few years ago. Thanks for sharing it with us.

1 Like