Table Of Contents

Previous topic

Can I do X or Y or Z in Sikuli?

Next topic

How to create Unit Testing Scripts for GUI

This Page

How to run Sikuli from Command Line

Sikuli IDE can be used on command line to run a Sikuli script or a Sikuli test case.

The usage on each platform:


PATH-TO-SIKULI/sikuli-ide.exe [options] or

PATH-TO-SIKULI/sikuli-ide.bat [options]

Mac OS X

/Applications/ [options]


PATH-TO-SIKULI/ [options]

Command Line Options


--args <arguments>

specify the arguments passed to Jython’s sys.argv


print this help message

Sikuli-IDE [--args <arguments>] [-h] [-r <sikuli-file>] [-s] [-t <sikuli-file>]
 --args <arguments>             specify the arguments passed to Jython's sys.argv
 -h,--help                      print this help message
 -r,--run <sikuli-file>         run .sikuli or .skl file
 -s,--stderr                    print runtime errors to stderr instead of popping up a message box
 -t,--test <sikuli-file>   run .sikuli as a unit test case with junit's text UI runner
-r,--run <sikuli-file>

run .sikuli or .skl file


print runtime errors to stderr instead of popping up a message box

-t,--test <sikuli-file>

run a .sikuli (.skl not possible) as a unit test with junit’s text UI runner (A script that can also be run in IDE’s Unit Test View).

Example - Run xxxx.sikuli with three arguments:


PATH-TO-SIKULIsikuli-ide.exe -r xxxx.sikuli —args a1 a2 a3


PATH-TO-SIKULI/ -r xxxx.sikuli —args a1 a2 a3

Mac OS X

/Applications/ -r xxxx.sikuli —args a1 a2 a3

Mac: using open to run a script

On Mac there is an alternative way to run a .skl file using open.

Mac OS X

open /Applications/ —args ABSOLUTE-PATH-TO-A-SKL

With “open -g”, you even can run a sikuli script without bringing Sikuli-IDE to the foreground. So the focus remains on the current window when executing a sikuli script.

Mac OS X

open -g /Applications/ —args ABSOLUTE-PATH-TO-A-SKL

Running sikuli-script.jar from Command line

New in version X1.0-rc2.

Interested in the Option -i (interactive Sikuli)?

If you follow these standards, you can do the following out of the box:

  • Windows: install Sikuli X using the installer (the system %PATH% will be set as needed)

    There is a new environment variable %SIKULI_HOME% that is expected to contain the directory, where Sikuli X is installed. You have to set it, if you have Sikuli X in a different place.

    Be aware: using the zipped version, you have to take care for %PATH% and %SIKULI_HOME% yourself.

  • Mac: have in its standard place /Applications. There is generally no need to put it elsewhere.

  • Linux: you generally have to take care for the environment yourself.

You might want to add more java options. They are left out here to concentrate on the point.

NOTE: In the commands below, some environment variables are only defined, to keep the lines short. The term path-to-your-script has to be specified according to your situation.

On Linux it should be principally like on Mac, with your specific adjustments.

Run a script without IDE


java -jar %SIKULI_HOME%\sikuli-script.jar path-to-your-script\yourScript.sikuli

Mac OS X


java -jar $SIKULI_HOME/sikuli-script.jar path-to-your-script/yourScript.sikuli

Run a script from Command line using the Sikuli contained Jython

This option might be helpful in some cases, where you want to have access to the Jython layer, before any Sikuli feature is touched. Be aware, that a from sikuli.Sikuli import * is needed to have access to Sikuli. You might have to take care somehow, that images are found, since bundle path is not set.


set SCRIPT=path-to-your-script\yourScript.sikuli\

java -cp %SIKULI_HOME%\sikuli-script.jar org.python.util.jython %SCRIPT%

Mac OS X


java -cp $SIKULI_HOME/sikuli-script.jar org.python.util.jython path-to-your-script/yourScript.sikuli/

Interactive Sikuli Jython Session from Command Line (Option -i)



Start an interactive Jython session with the Sikuli environment already in place.

This might be helpful to do some testing on commandline, without having to start the Sikuli IDE. A specified script and other options will be ignored.


java -jar %SIKULI_HOME%\sikuli-script.jar -i

Mac OS X


java -jar $SIKULI_HOME/sikuli-script.jar -i

This is a Mac sample session:

....$ java -jar /Applications/ -i
[info] Sikuli vision engine loaded.
[info] Mac OS X utilities loaded.
[info] VDictProxy loaded.
>>> Settings.ActionLogs=False
>>> Settings.InfoLogs=False
>>> Settings.DebugLogs=False
>>> img = capture()
>>> click(img)
>>> ret = click(img)
>>> Settings.ActionLogs=True
>>> click(img)
[log] CLICK on (1834,432)
>>> exit()