Frustrated with KM and the KM Forum – Maybe I'm Missing Something

I've been a KM user for what seems like the last 15+ years/versions of KM. The main reason I purchased the app was to handle App & Finder Window Management and to program easy hotkey triggers for frequently used app menu selections that had awkward and/or hard-to-remember app-programmed shortcuts.

Every time I turn to KM Forum to look up a subject I'm stuck on, I get TOTALLY LOST spinning from one fragmentary post to the other - each of which reveals 10 more subjects I need to then individually search out one by one. After an hour or so of spinning from one post to another, making an ever-growing list of the new subjects I need to study up on...I simply sign off, frustrated I rarely even found the answer to my original inquiry.

ON KM Forum I, personally haven't found any organized, general tutorials organized by subject matter or any type of indexed user manual where I can simply look up WINDOW MANAGEMENT and find a comprehensive collection of indexed information on that specific subject matter (which I assume would be a BIG subject for most users of KM).

Don't get me wrong, whenever I've posted a specific inquiry I received a lot of help from other users and Peter. But again it's learning about KM in a very fragmented way that takes a lot of searching and works to find the information I need. The Q&A section and Tips and Tutorial sections seem to be organized by date of post and not subject matter. Have I overlooked something somewhere? Is there or is there not a basic indexed manual or series of tutorials organized by subject on the fundamentals of KM macro programming? If there is - I haven't found it. And, if there isn't...isn't it time to create one?

All I know is I've been using KM for 15 years and I understand 1-2% of what it can do, and I find myself CONSTANTLY hoping to find some sort of manual organized by subject rather than spinning from one fragmented info nugget to the next when searching through post after post. I enjoy KM and I want to know all about it and its potential, but there HAS TO BE A BETTER WAY TO LEARN ABOUT THEM - but maybe I'm missing something big.


I'm sorry, I didn't realize I wrote a book instead of a post. My bad.


Maybe I'm misunderstanding the difficulties you've been facing, but it sounds like the User Manual, available from within the KM Editor under the Help menu or at

is akin to what you're looking for as a means to general KM guidance. The sections there might provide some of the overarching information you seek.

I think of the Forum here as a place for questions and answers, and as a place to read through others' situations as a means to glean uses for KM. That's not to suggest your view of this Forum should be the same. I say all this as someone who has used KM for longer than you have and feel similarly about how little I am able to utilize its capabilities.


Beginner KM user here, I can relate to your frustration. It’s not unique to KM forum, it’s the same when one searches for help online and find answers that are outdated (jquery what not) over new information. I find it’s the downside of the internet always remembers.

I’ve seen a few initiatives that help hint when something is old, just as a friendly reminder. The guardian puts a strip at the top when an article is more than a year old. Same could be done with posts.

Also, I've seen forums the standard is to update old threads when they’re obsolete. Requires a dedicated community, though.

Emphasize the use of solution. I have a running thread thread about web scraping, and by the nature of the thread it’s fragmented and shows experimentation, so I’m going to make a write up about the final solution. Maybe that can be encouraged as well.

I’ve mainly used Google to research before asking here, and here I think here lies a challenge: forum posts seem to get priority in search results over the RIDICULOUSLY WELL MAINTAINED WIKI!
This has meant my main entry to solutions has been forum posts, some very very old, instead of updated documentation.

I suggest rectifying this with stickied links to the wiki (on mobile, don’t see them right now) and maybe some effort can be made to bump up the wiki in search results?


Also worth mentioning every action has a linked Wiki article via right-click > Help.


Hey Joe,

Do you have any idea of how much work it is to build a comprehensive tutorial system?

Are you ready to put in a thousand hour initial investment and then many hours of maintenance?

Do you have the talent to do this really well?

The Keyboard Maestro Forum is a user-forum - i.e. a forum where users discuss a product and assist each other with using it. (We're very fortunate the developer hangs out here and contributes as much as he does.)

The forum is not a dedicated documentation site, although there is one:

The Keyboard Maestro Wiki

The Wiki is very comprehensive. It's not perfect, but we do the best we can with the time and energy we have available to spend.

@peternlewis is a one man shop, and the few other authorized Wiki editors are volunteers who work for no pay and little prestige.

Help is directly available for many things in the Keyboard Maestro Editor:

Press the Option key when mousing over commands in any of the Keyboard Maestro Editor's insert menus, and you'll see a help item.

Make sure you carefully review all the insert options – including all the Insert by Name dialogs – every one has a help item.

As @noisneil mentioned Help is also available in every action's gear menu and contextual menu:


Is Keyboard Maestro easy to learn how to use?

Yes – for basic use.

Is Keyboard Maestro easy to master?

NO – you'll never master it – although through significant effort you might become a power-user or even a super-user.

I've spent thousands of hours working with and learning Keyboard Maestro over almost 20 years, and I'm a bonafide super-user – but I still learn (and re-learn) stuff all the time. Some of that stuff is really hard to learn and stay current with. Some things I don't have the time and energy to mess with – but I'm always interested in things that can make my computer life better – and I improve my skills where I can.

  • I scan through nearly every post on the forum, and I bookmark or save things that are clearly of use.
    • I realize not everyone has the time or interest to do this.
  • I download other people's macros and deconstruct them to figure out how they work.
  • I regularly help people on the forum.
    • This is often challenging – helps keep my skills current – and helps me learn new things.
  • I ask for help when necessary.

If you want a good and well organized tutorial there is one, but you'll have to pay for it:

** What did you say about writing a book?  :sunglasses:



I agree with you, finding anything on the forum is quite a challenge. That's not really surprising though, the forum is exactly what it says on the box - a forum. It's a place to ask questions and get answers.

I suggest rather than spend a long chunk of time searching the forum, for any given problem the sequence would be:

  • Try implementing it yourself.
  • If you can't figure it out in ten minutes, try searching the wiki or the forum.
  • If you can't find an answer in ten minutes, post a question. Make sure you specify what you are trying to accomplish, more so that how you are trying to accomplish it (unless it is a skill you want to learn). Include what you have tried, and your (simplified) macro, and any data you want to process, details of target applications, etc.
  • After posting a question, continue with the above, searching and trying things yourself - if you manage to solve the problem, great, answer your own question on the forum so anyone else who comes along with a similar problem has a chance of finding it and no one will waste any further time trying to answer it. If not, there is a good chance someone will answer it. And maybe their answer will be "this is covered on this other thread", and that's ok too. No one should fault you for failing to find a specific topic (not presuming you made at least some effort to do it). Pointing people at the right topic or the right chunk of documentation is a big part of what the forum’s purpose is.

So basically, put a bit of effort in to start, to get familiar with the problem, and search a bit for the answer. But don't spend too long stuck - ask your question, and let the forum do it's thing. That is where the forum and all its wonderful participants shine.


Rather than echo the above, I'll go specific...

KM is built on fundamentals. Three of those are:

  1. You can get values using Functions, Tokens, and some Actions
  2. You can can manipulate values using Calculations and some Actions
  3. You can use values in the fields of Actions to change things

(There are also sections in the manual explaining Tokens, Calculations, Variables, etc.)

Examples of these with respect to window manipulation can be found in KM itself, in the "Manipulate a Window" action. If you change the first option to "Move and Resize"->"Top Left":


...the action becomes:


...and, straight away, you see how you can use a Function (SCREENVISIBLE) manipulated by a Calculation (*50%) to change the height of the front window of the front application. More complicated operations simply build on those fundamentals.

Now, perhaps I'm in the minority because I don't do much window manipulation (I work in a mess of windows and I'm happy that way :wink: ). What more would you want from a "Window Management HOWTO"?

That's a serious question, btw. A good way to write such documentation is to start with someone who is having problems doing something and use their issues as the outline for the HOWTO. So post your "ideal outline" for a "Window Management HOWTO" and, perhaps, the Forum can flesh it out into something you can submit as a one-stop shop for other users.

Rinse and repeat for other subjects you get stuck on and you'll have your "organized, general tutorials organized by subject matter" in no time!


People don't find it easy to ask good questions, and many fall straight into the XY problem trap.

That leaves a spreading wake of thread titles which are much less likely to be found by later searches.

Perhaps worth tweaking titles to improve search harvests ?


XY problem may be classified as one of the "Knowledge Paradox"'s consequences: you don't know what you don't know. So, the real problem may have a wider context - since you can't even imagine what you don't know, you tend to think that you know everything here, thus the way you are following is the only right way ("tried everything", "use known methods"). People will listen to advice if they doubt their way, but they are often so sure, or not willing to try another way because it may take a step back.

Welp, I just learned something new today! Thanks for pointing this out.

Hello Everybody,

Two suggestions:

  1. Having a specific post where the user may ask for a specific solution for which he/she is willing to pay. Then, the "seller" has two prices according to the fact whether the solution may be published (for everyone to enjoy) or not.

  2. Make a crowdfunding to make (and eventually maintain) a good manual.

I will end up by purchasing the mentioned manual (Keyboard Maestro Field Guide | MacSparky Field Guides) in a couple of months or so, but meanwhile I suggest all the KM community should take into consideration these two suggestions.


See under Enclosure ?


"Proper" solutions cost proper money. "Specific" solutions will probably start with an half-hour Zoom call (billable!) where the workflow is demonstrated and questioned, then there's the time taken to replicate the customer's environment (billable!), development and testing time (billable!), documentation (billable!), on-going support (billable!)...

I'm sure there are "proper" KM devs that will do the above, if the people willing to pay go look for them.

But the beauty of KM is that it is quite easy to take snippets and examples from the Forum and adapt them to your own needs -- and nobody is more in tune with your own needs than you are! Some basic knowledge gleaned from the manual and follow-ups on the Wiki will get you most of the way there, and for the tricksie stuff this Forum is really helpful -- for free!

Yes, that can require a little more work -- but you get exactly what you need plus a little extra KM skill to make things easier the next time.

Of course, the current manual and Wiki aren't to everyone's taste, which brings us to:

What is a good manual? To me, it is the current one, the Wiki, and the Forum -- those, plus just messing around writing macros, have been enough to give me a reasonable handle on KM over the last few months. But that makes me a very bad choice as a manual writer for those who don't "grok" the current resources, because I'd just reproduce what's already there in a slightly different (and probably worse) way.

Writing a good manual is skill all of its own. I've not seen the MacSparky KM field guide but I've heard good things about it (and the other guides David Sparks has written) and, based on how he presents the Automators podcast, I'll happily recommend it "blind".

More specific HOWTOs are an easier thing for a Forum to work on together, and they could build into a good, organised, resource that falls nicely between the highly specific Forum responses and an "all the things" manual. But, to repeat my point from above, a good way to write such documentation is to start with someone who is having problems doing something and use their issues as the outline for the HOWTO -- after all, the people who already know the answers probably don't realise there's a problem!

So post some outlines for the HOWTOs you'd like to see, and let's go to work.


I mostly agree with you but I'd like to precise on what I do not agree. I really like your answer since you bring along the fact that a good manual is something to be defined. In order to do so, I need time which I do not have right now. I'll post my answer at begining of February. Right now I'm in the middle of something and cannot document my point of view with examples. Meanwhile, of course, I'll be reading whatever others might post.

My unique purpose, after all, is to make KM more accessible to more non-programmers.

I sincerelly thank you for your reply, Nige_S, and I'll continue to reply next February. I'd like to be constructive in this point since I really think both Keyboard Maestro's manual and forum needs another (complementary) aproach.

Thank you all.

Keep in mind that @peternlewis has been developing Keyboard Maestro for about 20 years now, and he's been in the developer game since around 1993.

Keyboard Maestro's documentation has evolved considerably over its lifetime.

The Wiki is an evolving entity and the latest, greatest version of the manual – it links directly into the Keyboard Maestro Editor itself.

Keyboard Maestro Wiki

Note that there's a downloadable PDF manual available as well:

PDF Keyboard Maestro 10 Manual

You'll have to bring something really worthwhile to the table in order to entice Peter to spend precious time, energy, and money on it. He's a one man shop and family man, and those commodities hard to come by.


Hello, ccstone and everyone else:

Perhaps it is time to help Peter (and whoever else is directly involved in the code of KM) to make a much better Manual and Forum. He has already done much for all of us and it is time to pay him back while learning even more about how to use KM. I believe in a serious collaborative way to do it. And serious means that perhaps some of the experts (I'm not by no means an expert myself) might be willing to get involved for some (even if it is a symbolic quantity) money. But as I say, in order to be constructive I need some time which I will not have until February.

More accurately -- a good manual is in the eye of the beholder. I think KM already has a good manual, but that's because it suits the way I think and learn. And that's why any such endeavour needs a lot of input from "not-me" :wink:

You'll hate me for saying this but now is the ideal time to make a note of those KM things you wish there was a HOWTO for :wink: With no time to go hunting for answers when you're under the gun, any problems will be brought into stark relief. A quick Note, back to your work, flesh it all out when you have more time.


Long time user here, and I almost never post. However, reading this thread I learned a whole bunch of new ways to figure out a problem. Above ccstone showed me how to get help files, although it is a right click, (option key plus click), my kensington 10 button track ball I use the right key, I never knew that existed. Also, looking at the info on the Keyboard Maestro Field Guide it appears to have lots of info, but a couple of draw backs of course are the $49 price tag, as well as it hasn't been updated in almost 2 years. I can't imagine my MAC not using KM, and only wish there was an equal for Windows. That OS is a mess. Kudos to Peter for keeping this blog alive. Lastly, yes, it is hard to find stuff here. I have spent my fare share of time searching. :wink:


Unfortunately Discourse's search engine is not particularly wonderful...