ConEmu GuiMacro

GUI macros are the set of functions allowing to control ConEmu window and its consoles.

GuiMacro may be triggered from many places, for example from command line or keypress.


How GuiMacro may be executed

1. ConEmu hotkeys ‘Macro 01’ … ‘Macro 32’

Just set up ‘Macro 01’ … ‘Macro 32’ on ‘Keys’ page of ‘Settings’ dialog.

2. ConEmuC -GuiMacro switch

NB. This does not work in WSL!

If you may call ConEmuC.exe (command line, batch file, etc.) then you may use ConEmuC -GuiMacro switch. The format is flexible, few examples below.

"%ConEmuBaseDir%\ConEmuC.exe" /GUIMACRO WindowMinimize
ConEmuC -GuiMacro palette 1 "<Solarized>" -guimacro WindowMaximize
ConEmuC -guimacro status 1 test
ConEmuC -Guimacro Flash(1,3,5) ; MsgBox("Notification text")
ConEmuC -GuiMacro:0 print: C:\Program Files (x86)\Adobe\Reader 10.0\Reader\AcroRd32

3. [From shortcut (ConEmu and ConEmu64)]

ConEmu.exe -Detached -GuiMacro "Create(0,1); Context; print(\"echo \\\"Hello world\\\"\");"

4. ANSI OSC code

The following is only a demo, if you need to check ‘IsConEmu’ it is better to call "ConEmuC -IsConEmu" and check %errorlevel%.

rem We need real ESC code (symbol with ASCII \x1B) in cmd scripts
call SetEscChar.cmd
echo %ESC%]9;6;"IsConEmu"%ESC%\
if "%ConEmuMacroResult%"=="Yes" echo ConEmu found!

5. Via Far Manager plugin

NB. Far Manager 1.7x, 2.0, 3.0 are supported.

F11 -> ConEmu -> Execute ConEmu macro

6. Via Far Manager macros, Far3-lua


7. Far3-pre-lua (callplugin is alias of Plugin.Call)


8. Far2



ConEmu GuiMacro parser is flexible and support different styles.

Styles of arguments specification

  • surrounded by brackets:
  • delimited by space:
Function Arguments
  • delimited by colon (and space optionally):
Function: Arguments

Note Using colon-style you may easily pass one-string-argument. Other methods may require quotating, backslash-escaping or verbatim strings.

print: C:\Program Files (x86)\Adobe\Reader 10.0\Reader\AcroRd32
print("C:\\Program Files (x86)\\Adobe\Reader 10.0\\Reader\\AcroRd32")
print(@"C:\Program Files (x86)\Adobe\Reader 10.0\Reader\AcroRd32")

Specifying more that a one argument

  • delimited by commas:
  • delimited by spaces:
Function Arg1 Arg2 Arg3

Executing several functions at once

  • delimited by semicolons:
print("abc"); keys("^_"); print("def")
  • delimited by -GuiMacro when called from your shell prompt:
ConEmuC -GuiMacro print abc -GuiMacro keys "^_" -GuiMacro print def

Numerical arguments

  • decimal form with leading optional ‘+’ or ‘-’:
  • hexadecimal form with ‘0x’ or ‘0X’ prefix:

String arguments

It is recommended to put string arguments in doublequotes, but in fact that is not required for ‘one-word’ arguments.

C-style strings

Backslashes and doublequotes must be escaped with backslashes.

Special symbols can be specified using escaped form:

\\  --> \
\"  --> "
\r  --> Carriage return (ASCII 13)
\n  --> New line (ASCII 10)
\t  --> Horizontal tab (ASCII 9)
\b  --> Backspace (ASCII 8)
\e  --> Escape (ASCII 27)
\a  --> Alert (ASCII 7)

And hexadecimal form \xNNNN (up to 4 digits) may be used to specify exact unicode character:

\x1B   --> same as \e (ASCII 27)
\x044F --> russian ‘я’ letter


print("\eCD /d \"C:\\Users\"\n")

Verbatim strings

No ‘escaped’ symbols, with the only exception of doublequote - they must be doubled.

print(@"CD /d ""C:\Users""")

Far plugin notes

When you run some GuiMacro’s from Far Manager macro and the string has backslashes ("C:\\Users\\...") you need to use verbatim strings or double-double them because ConEmu GuiMacro parser always parse escaped symbols itself. The GuiMacro may be called from many places (from command line for example) and parser is the one for all inputs.


Command line (ConEmuC and ConEmuC64)

It doesn’t matter ConEmuC.exe or ConEmuC64.exe you are using.


ConEmuC [/SILENT] /GuiMacro[:PID|HWND][:T<tab>][:S<split>] <GuiMacro command>
ConEmuC [-Silent] -GuiMacro[:PID|HWND][:T<tab>][:S<split>] <GuiMacro command>
SILENT Suppress output of GuiMacro result (OK, FAILED, etc.)
PID ‘Process ID’, decimal number
0 Special value means ‘Use active tab/split of the first found ConEmu window
ConEmu GUI PID ConEmu.exe or ConEmu64.exe, macro will be executed in the active tab/split
Console server PID ConEmuC.exe or ConEmuC64.exe started with /ROOT argument
HWND Window descriptor, hexadecimal number with x prefix
ConEmu GUI HWND Main ConEmu window, macro will be executed in the active tab/split
Console server HWND The hidden real console window
T<tab> Changes affected RealConsole, ‘tab’, decimal 1-based tab index
S<split> Changes affected RealConsole, ‘split’, decimal 1-based pane index of selected/active group of panes

When GUI macro executed, ConEmuC.exe set errorlevel to 0 and write result to ‘StdOut’.

When you execute macro without PID or HWND,

ConEmuC -GuiMacro print abc

your macro will be executed in the current console (tab/split), if it was started in ConEmu. On the other hand, if you try to call that outside of ConEmu, execution will fails with ‘%errorlevel% == 134’, because your console (where you are trying to execute macro) is not a ConEmu console.

So, if you need to execute macro from any external application (Visual Studio, Sublime text, even from Win+R) you may specify exact instance with PID or HWND.

  • PID must be decimal number.
  • HWND must be specified as hexadecimal number (window descriptor) with ‘x’ prefix.

Exact values you may see in the ConEmu status bar, in the Windows Task Manager, or find yourself using Windows API.

Few examples:

ConEmuC -GuiMacro:0 print: C:\Program Files (x86)\Adobe\Reader 10.0\Reader\AcroRd32
ConEmuC -GuiMacro:8204 print "This is sample text"
ConEmuC -GuiMacro:x140F32 WindowMinimize

Run from shortcut (ConEmu and ConEmu64)

If you need to run some GuiMacro(s) after ConEmu starts user may use -GuiMacro switch with ConEmu.exe or ConEmu64.exe. Only one -GuiMacro switch may be specified, but you may delimit functions with semicolon. Also, double quotes and backslashes must be properly escaped within string arguments.

The following example will start ConEmu window without tabs, show ‘Create new console’ dialog and prints into the created console echo "Hello world".

ConEmu.exe -Detached -GuiMacro "Create(0,1); Context; print(\"echo \\\"Hello world\\\"\");"

Far Manager plugin

You may run GuiMacro from Far Plugin (ConEmu.dll / ConEmu64.dll) from:

  • Using menu command: F11 -> ConEmu -> Execute ConEmu macro
  • Using Far Manager macro language, Far v3.x Lua:
  • Far v3.x pre Lua:
  • Far v2.x:

When you call plugin menu, result is show in the dialog field.

When you use Far Manager macro, the result is placed to the “ConEmuMacroResult” environment variable, or returned via string result if you are using Far 3.0 with Lua.

List of functions

Optional parameters are italic.

Show ‘About’ dialog with selected page activated

  - Show ‘About’ dialog with page activated, e.g. ‘About("-new_console")’

Start Alt+Number mode

  - Start Alt+Numbers mode: Base = 10 or 16

Change affinity and priority of active console

AffinityPriority( *Affinity*, *Priority* )
  - Call without arguments to show affinity/priority dialog
    Affinity: Number - processor mask, same as WinApi's SetProcessAffinityMask
              "" - empty string means ‘don't change’
    Priority: Number - priority class, same as WinApi's SetPriorityClass
              "" - empty string means ‘don't change’

Attach external console or ChildGui by PID

  - Attach console or ChildGui by PID

Generate CTRL+C or CTRL+BREAK signals

  - Event==0: Generates a CTRL+C signal
    Event==1: Generates a CTRL+BREAK signal
    More info in GenerateConsoleCtrlEvent WinAPI function

Close or kill active tab, group or window

  - Close current console (0), without confirmation (0,1),
    terminate active process (1), without confirmation (1,1)
    close ConEmu window (2)
    close active tab (3)
    close active group (4)
    close all tabs but active (5)
    close active tab or group (6)
    close all active processes of the active group (7)
    close all tabs (8)

Change macro execution context

Useful after creating new consoles or switching tabs.

  - Change macro execution context
    Tab: 1-based tab index
    Split: 1-based split index

Copy console contents or selection, plain text or HTML

  - Copy active console contents
    What==0: current selection
    What==1: all buffer contents
    What==2: visible area contents
    Format==0: plain text, not formatting
    Format==1: copy HTML format
    Format==2: copy as HTML
    File: if specified - save to file instead of clipboard

Create debugger console or memory dumps

  - Create debugger console or memory dumps
    Action==0: Debug active process
    Action==1: Active process memory dump
    Action==2: Active process tree memory dump

Detach active RealConsole from ConEmu

  - Detach active RealConsole from ConEmu

Find and activate Far Manager window, used in macro ‘ConEmu.Editor.lua’

 - Returns "Found:<index of RealConsole>", "Active:<Far window number>", "Blocked", or "NotFound"
   <WindowType> is number from Far Manager enum WINDOWINFO_TYPE

Flash taskbar icon or window caption

  - Allows to flash taskbar icon and/or window caption
    Flash(0) - Stop all flashing
    Flash(0,1) - Simple flashing (see MSDN FlashWindow)
  - Special flashing (see MSDN FlashWindowEx)
    Flags: 0 - stop, 1 - caption, 2 - taskbar, 3 - caption+taskbar, etc.
    Count: the number of times to flash the window

Change font face name and (optionally) height/width

 - Change font face name and (optionally) height/width.

Change font height in the ConEmu window

 - Change font height in the ConEmu window
   Relative==0: N - required font height in points
   Relative==1: N (+-1, +-2) - increase/decrease font height
   Relative==2: N (per cents) - alias for Zoom(N)
   returns - "OK", or "InvalidArg"

Returns value of some ConEmu environment variables

Macro returned requested information from GUI (ConEmu.exe or ConEmu64.exe)

  - Returns values of some ConEmu environment variables
    Processed in GUI so the result may differs from RealConsole env.vars
    "PID": %ConEmuPID% and so on
  - Returns additional information about RealConsole
    "Root": XML with RootProcess info
    "ActivePID","CurDir": as is

Returns value of some ConEmu options

 - Returns value of some ConEmu options (the set is limited)

Group keyboard input for visible splits

 - Group keyboard input for visible splits
   Cmd==0: switch mode (default)
   Cmd==1: group
   Cmd==2: un-group

Switch highlighting under mouse cursor

 - Switch highlight under mouse cursor (off/row/col/row+col/...)
 - What: 1 - row, 2 - col, 3 - row+col
   Act:  0 - off, 1 - on,  2 - switch (default)

Check if console is started under ConEmu (check ConEmuC alternative)

 - Returns "Yes" when console was started under ConEmu
   Alternative is "ConEmuC.exe -IsConEmu" and checking errorlevel

Check if tab (RealConsole) is active or not

 - Check, is RealConsole active or not, "Yes"/"No"

Check if RealConsole is visible or not

 - Check, is RealConsole visible or not, "Yes"/"No"

Post special keystrokes to the console (AutoHotKey syntax)

 - Post special keystrokes to the console (AutoHotKey syntax)
   Mod: ^ - LCtrl, >^ - RCtrl, ! - LAlt, >! - RAlt, + - Shift
   Example: Keys("^_") will post ‘Ctrl+_’

Show modal GUI MessageBox, returns clicked button name

 - Show modal GUI MessageBox, returns clicked button name
   ("Ok", "Cancel", "Retry", etc.),
   ButtonType (number) is from Windows SDK.

Change or acquire current console palette

  - Returns current palette name, change if <Cmd> specified
     Cmd==0: return palette from ConEmu settings
     Cmd==1: change palette in ConEmu settings, returns prev palette
     Cmd==2: return palette from current console
     Cmd==3: change palette in current console, returns prev palette
     NewPalette: palette name (string)
     NewPaletteIndex: 0-based index (number)

Paste specified text or Windows clipboard contents

 - When <Text> is omitted - paste from Windows clipboard,
   otherwise - paste specified text
   Cmd==0: paste all lines
   Cmd==1: paste first line
   Cmd==2: paste all lines, without confirmations
   Cmd==3: paste first line, without confirmations
   Cmd==4: select and parse file pathname, Text - default
   Cmd==5: select and parse folder pathname, Text - default
   Cmd==6: select and parse cygwin file pathname, Text - default
   Cmd==7: select and parse cygwin folder pathname, Text - default
   Cmd==8: paste path from clipboard converted to CygWin style
   Cmd==9: paste all lines space-separated
   Cmd==10: paste all lines space-separated, without confirmations

Paste active Explorer window path into ConEmu

PasteExplorerPath (<DoCd>,<SetFocus>)
  - Activate ConEmu and ‘CD’ to last (top in Z-order) Explorer window path
     DoCd: 1 - ‘CD’, 0 - paste path only
     SetFocus: 1 - bring ConEmu to the top, 0 - don't change active window

Paste specified or selected file contents

 - Paste <File> contents, omit <File> to show selection dialog
   Cmd==0: paste all lines
   Cmd==1: paste first line
   Cmd==2: paste all lines, without confirmations
   Cmd==3: paste first line, without confirmations
   Cmd==9: paste all lines space-separated
   Cmd==10: paste all lines space-separated, without confirmations
   If "<CommentMark>" specified - skip all lines starting with prefix

Pause or un-pause current console

  - Pause current console
     Cmd==0: switch mode (default)
     Cmd==1: pause
     Cmd==2: un-pause

Print (paste) specified text

 - Alias for Paste(2,"<Text>")

Set progress state on taskbar and ConEmu title

 - Set progress state on taskbar and ConEmu title
   Type=0: remove progress
   Type=1: set progress value to <Value> (0-100)
   Type=2: set error state in progress with <Value>
   Type=3: set indeterminate state in progress
   Type=4: set paused state in progress with <Value>

Create new or restart active tab or pane

Recreate(<Action>[,<Confirm>[,<AsAdmin>]]), alias "Create"
 - Create new tab or restart existing one
    Action: 0 - create tab, 1 - restart tab, 2 - create window
    Confirm: 1 - show ‘Create new console’ dialog, 0 - don't show
    AsAdmin: 1 - start elevated tab

Rename active tab or console title

 - Rename tab (Type=0) or console title (Type=1)

Scroll console contents

 - Do buffer scrolling actions
   Type: 0; Value: ‘-1’=Up, ‘+1’=Down
   Type: 1; Value: ‘-1’=PgUp, ‘+1’=PgDown
   Type: 2; Value: ‘-1’=HalfPgUp, ‘+1’=HalfPgDown
   Type: 3; Value: ‘-1’=Top, ‘+1’=Bottom
   Type: 4; No arguments; Go to cursor line

Start or change console selection

 - Used internally for text selection
   Type: 0 - Text, 1 - Block, 2 - Stop
   DX: select text horizontally: -1/+1
   DY: select text vertically: -1/+1
   HE: to-home(-1)/to-end(+1) with text selection
   HE: word-left(-2)/word-right(+2) with text selection
 - Use to cancel active selection

Change used DPI for ConEmu window (debug purposes)

 - Change effective dpi for ConEmu window: 96, 120, 144, 192

Try to set focus in ConEmu window

 - Try to change active window
   Type: 0 - Set focus into ConEmu window/process (default)
   Type: 1 - Switch focus between ConEmu and ChildGui
   Type: 2 - Set focus into ChildGui window of the active console
   Type: 3 - Set focus into the parent of the ConEmu window (ConEmu Inside mode)

Change setting by numeric ID of the checkbox

   ID: numeric identifier of checkbox (ConEmu.rc, resource.h)
   Value: 0 - off, 1 - on, 2 - third state
   Read about SetOption below

Change some setting by name

 - Name=one of allowed for changing ConEmu options
   IsRelative=1 to use relative instead of absolute for some options
   "AlphaValue": set transparency level of active window
     Value: 40 .. 255 (255==Opaque)
   "AlphaValueInactive": set transparency level of inactive window
     Value: 0 .. 255 (255==Opaque)
   "AlphaValueSeparate": enable separate active/inactive transparency level
     Value: 0(disable) .. 1(enable)
   "AlwaysOnTop": place ConEmu window above all non-topmost windows
     Value: 2 - toggle, 1 - enable, 0 - disable
   "bgImage": change background image
      Value: file or color, e.g. "C:\image.jpg" or "#3182a4"
   "bgImageDarker": darkening of background image
     Value: 0 .. 255
   "FarGotoEditorPath": path to the highlight/error editor
     Value: path to the executable with arguments (Issue 1704)
   "QuakeAutoHide": auto hide on focus lose, Quake mode
     Value: 2 - switch auto-hide, 1 - enable, 0 - disable

Change ConEmu parent window

 - Change ConEmu parent window during Inside mode
   HWND: new parent window handle

Show ‘Settings’ dialog with specified (optionally) page activated

 - Show ‘Settings’ dialog with specified page activated (optionally)
     PageResourceId: integer DialogID from ‘resource.h’

Start any process inside or outside of ConEmu window

 - Verb can be "open", "print" and so on, or special value "new_console",
   which starts File in the new tab of ConEmu window. Examples:
     Shell("","","cmd.exe /k -new_console:b"),
     Shell("new_console:b","","cmd.exe /k")
     Shell("new_console:Ibn","cmd","/k start explorer \"%CD%\" && exit")

Do some sleeping

 - Milliseconds: max 10000 (10 seconds)

Create and control splitting of active group

 - Cmd=0, Horz=1..99, Vert=0: Duplicate active ‘shell’ split to right, same as Shell("new_console:s50Hn")
   Cmd=0, Horz=0, Vert=1..99: Duplicate active ‘shell’ split to bottom, same as Shell("new_console:s50Vn")
   Cmd=1, Horz=-1..1, Vert=-1..1: Move splitter between panes (aka resize panes)
   Cmd=2, Horz=-1..1, Vert=-1..1: Put cursor to the nearest pane (preferred direction may be choosed)
   Cmd=3, Maximize/restore active pane

Show/Hide StatusBar or set its text

 - Show/Hide status bar, Parm=1 - Show, Parm=2 - Hide
 - Set status bar text

Control ConEmu TabBar

 - Control ConEmu tabs
   Cmd==0:  show/hide tabs
   Cmd==1:  commit lazy changes
   Cmd==2:  switch next (eq. CtrlTab)
   Cmd==3:  switch prev (eq. CtrlShiftTab)
   Cmd==4:  switch tab direct (no recent mode), Parm=(1,-1)
   Cmd==5:  switch tab recent, Parm=(1,-1)
   Cmd==6:  switch console direct (no recent mode), Parm=(1,-1)
   Cmd==7:  activate console, Parm=(1-based console index, -1 for the last tab, -2 for the tab of execution)
   Cmd==8:  show tabs list menu (indiffirent Far/Not Far)
   Cmd==9:  close active tab, same as Close(3)
   Cmd==10: switches visible split-panes, Parm=(1,-1)
   Cmd==11: activates tab by name, title or process name
   Cmd==12: return tabs list "1: tab1\n2: tab2\n..."

Start specified Task

 - start task with 1-based index
 - start task with specified name

Create new Task and save it to Settings

 - create new task and save it to settings

Changes active terminal modes

  - changes active terminal modes
    Mode==0: Keyboard emulation (Xterm/Windows)
    Mode==1: Bracketed paste
    Mode==2: Application cursor keys (DECCKM)
    Action==0: Disable mode
    Action==1: Enable mode
    Action==2: Switch mode (default)

Change ConEmu window transparency level

 - Change ConEmu window transparency level
   Cmd = 0, Value = 40..255 (255==Opaque)
   Cmd = 1, Value = <relative inc/dec>
   Cmd = 2, Value = 0..255 (255==Opaque) - for inactive window
   Cmd = 3, Value = <relative inc/dec> - for inactive window
   Cmd = 4, Value = <0/1> - AlphaValueSeparate

Open online documentation

 - Open online documentation

Change ConEmu window mode

 - Switch fullscreen window mode
   returns previous window mode
 - Switch maximized window mode (Cmd==0)
 - Maximize window by width (Cmd==1) or height (Cmd==2)
   returns previous window mode
WindowMinimize() or WindowMinimize(1)
 - Minimize ConEmu window ("1" means "minimize to the TSA")
 - Returns or set current window mode
   "NOR", "MAX", "FS" (fullscreen), "MIN", "TSA"
   "TLEFT", "TRIGHT" (tile to left/right),
   "THEIGHT", "TWIDTH" (tile/maximize height/width),
   "MPREV", "MNEXT" (move ConEmu to prev/next monitor)
   "HERE" (move ConEmu to monitor with mouse cursor)

Change ConEmu window geometry

WindowPosSize("<X>", "<Y>", "<W>", "<H>")
  - Change ConEmu window geometry
    "<X>" and "<Y>" are pixels (numbers in doublequotes);
    "<W>" and "<H>" may be cells, percentage or pixels:
      "80", "40%", "800px".

Write Text to console output

Use it at you own risk! Calling this function may cause unexpected behavior of running console application! That is because function changes console contents and cursor position directly, bypassing detouring standard ConIn/ConOut processing queue.

  - Write text to console OUTPUT

In most cases safe functions Paste, Print and Keys are preferable!

However, with Write you may implement some interesting features, like printing sort of ‘hints’ in shell prompt:

Write "\e7\e[90mEcho \"Hello world!\"\e[m\e8"

Or push to console several colored lines to ‘mark’ some point in real-time logs (tail -f).

Write "\n\n\e[91m========== '\e]9;8;\"time\"\e\\' ==========\e[m\n\n"

Change font zoom value

 - Set zoom value, 100 - original font size


You may change some (or most) of ConEmu settings using SetOption macro function.

It may be used by name for several options, for example

SetOption("FarGotoEditorPath","far.exe /e%1:%2 \"%3\"")

Or by CheckBox/RadioButton ID. Of course you must know that number-ID. Look up the control by its label in the ConEmu.rc (don’t forget about possible ‘&’), and then look up the exact number-ID by its string-ID in the resource.h.

For example, turn scrollbar on:

ConEmuC -GuiMacro SetOption Check 2488 1

Turn Quake style activation off:

ConEmuC -GuiMacro SetOption Check 2333 0


Examples below show how to call GuiMacro from different versions of Far Manager. All of them checks and show message if ‘Far started under ConEmu’.

Also, Far 3 examples show how to run and new instance of far.exe in the new ConEmu tab. These are just an examples of using Far Macro language.


local conemu = "4B675D80-1D4A-4EA9-8436-FDC23F2FC14B"

if Plugin.SyncCall(conemu,"IsConEmu")=="Yes" then
  far.Message("Far started under ConEmu","Macro")

local cmd = ('shell("open",@"%s")'):format(win.GetEnv"FARHOME"..[[\Encyclopedia\]])

local cmd = ('shell("new_console",@"%s")'):format(win.GetEnv"FARHOME".."\\far.exe")


$if (callplugin("4b675d80-1d4a-4ea9-8436-fdc23f2fc14b","IsConEmu()")!=0 && env("ConEmuMacroResult")=="Yes")
  MsgBox("Macro", "Far started under ConEmu")




$if (callplugin(0x43454D55,"IsConEmu()")!=0 && env("ConEmuMacroResult")=="Yes")
  MsgBox("Macro", "Far started under ConEmu")


This is most complicated, cause of ‘callplugin’ absence in the Far 1.x

$if (menu.Select("ConEmu",2)<=0) MsgBox("ConEmu","Plugin was not found in list!",1)
Enter %r="";
$if ("~.",1)>0)
  ~ $Text "IsConEmu()" Enter %r=Dlg.GetValue(5,0);
$if (%r=="Yes")
  MsgBox("Macro", "Far started under ConEmu")
Download    Donate