Command Line

Running sketches in the Processing IDE is cool, but running them in the command-line is even cooler! Running in the command-line means you can automate your sketches, run them without opening the IDE, run sketches on embedded devices, or have sketches run on boot... all super useful!

Installing the processing-java command

• Windows/Linux: use the processing-java program that's in the download
• Mac: in the Processing app, go to Tools > Install "processing-java"

processing-java options are:

COMMAND	INFO
--help	Show this help text :)
--sketch=<path>	Specify the sketch folder (required)
--output=<path>	Specify the output folder (optional and cannot be the same as the sketch folder)
--force	The sketch will not build if the output folder already exists, because the contents will be replaced; this option erases the folder first: use with extreme caution!
--build	Preprocess and compile a sketch into .class files
--run	Preprocess, compile, and run a sketch
--present	Preprocess, compile, and run a sketch in presentation mode
--export	Export an application
--no-java	Do not embed Java: use at your own risk!
--platform	Specify the platform (export to application only), should be one of: windows, macosx, or linux

A few things to note:

• The --build, --run, --present, or --export commands must be the final parameter passed to processing-java (unless using --platform, which should come after --export)
• Arguments after the ones listed above will be passed through to the sketch itself, and therefore available to the sketch via the 'args' field! (See example below)
• To pass options understood by PApplet.main(), write a custom main() method so that the preprocessor does not add one

Examples

Some examples for using processing-java...

• Run a sketch without any special options:
  processing-java --sketch=/full/path/to/your/sketch/folder --run
  Note: the --sketch command is required and should be the path to your sketch's folder
• Save a file, specifying a folder other than where the sketch is located:
  processing-java --sketch=/full/path/to/your/sketch/dir --output=/path/to/output/folder --run
• Include the optional --force command, which will overwrite the output directory even if there's something there (use with caution!):
  processing-java --sketch=/full/path/to/your/sketch/dir --output=/path/to/output/folder --force --run
• Run a sketch in presentation mode:
  processing-java --sketch=/full/path/to/your/sketch/folder --present

Adding command-line arguments:

If you want to include arguments passed from the command line into your sketch, you can add them after the --run, --present, etc commands. For example, here we pass the width and height to a sketch:

processing-java --sketch=/full/path/to/your/sketch/folder --present 600 600

In your sketch, you can access the arguments like this:

void settings() {
    // if there are arguments, change the sketch's size
    if (args != null) {
        int w = Integer.parseInt(args[0]);
        int h = Integer.parseInt(args[1]);
        size(w, h);
    }
    // might want to have an option if arguments are
    // not present or incomplete – here we just set the
    // size manually :)
    else {
        size(400, 400);
    }
}

Common issues

A few common things that might go wrong:

Error Sketchname does not exist
This can be because the full path to the sketch was not specified using the --sketch argument or that the folder containing the sketch is different from the sketch's name.

processing-java previously installed but no longer working
On Mac OSX, you may need to reinstall the command line tool after downloading a new version of Processing :(

Running headless

Running your sketch "headless" (ie without a display) may require some extra work, see Running Without a Display for more info.

The --build and --export options should even work in headless mode when enabled. If you run into trouble building or exporting from the command-line, please let us know by posting a bug report.