It started when I was playing with LaunchBar search templates. I tried the man page search and it opened a nice window in Terminal. But I didn’t want to open Terminal when iTerm was already running.

My initial search said it wasn’t possible, but in fact it’s really easy. I found this gist, which solved the problem.

iTerm profiles can be set to handle URL handlers, including x-man-page, which is what the search template uses. If you create a new profile (call it “Man Page”) and under General, change “Login Shell” to “Command” and paste this in:

bash -c "echo $$HOST$$ | sed -E 's/(.*)\/(.*)/\1 \2/' | xargs man"

Then at the bottom of the General pane, locate “URL Schemes,” and choose x-man-page from the dropdown. It will ask you if you want to make iTerm the default handler — click Yes (that’s the point of this).

That’s the minimum you have to do. I went ahead and customized the color scheme, set the window to 80 columns, and added a little transparency and blur under Window settings. Under Session settings, I made sure that it was set to close when the command terminated, and disabled the warning about early termination, which was just annoying when I mistyped command and needed to try again.

iTerm man page themes

Here are the color schemes I made, both light and dark. I’m generally a “dark” guy in Terminal, but I kind of liked the light theme that Terminal used for man pages. I made it less yellow, and added contrasting colors for bold and underline text, which looks great when viewing man pages. Customize to your heart’s content.

It’s a pretty cool trick, hopefully it helps those who didn’t already know about it. Once you have it set up, you can use x-man-page://[COMMAND] anywhere you like, including aliasing it in your shell or creating a function. In Fish it would be:

function nman --description 'Open man pages in a new terminal window'
    open "x-man-page://"$argv
end

Have fun!