Complete reference for the opal executable, as of Opal 2.0.

Usage: opal [options] -- [programfile]

Options are defined in lib/opal/cli_options.rb. Anything after -- is passed to the compiled program as ARGV.

Read this first. Several short flags do not mean what their letter suggests.

Valid --compile-to-exe runtimes come from Opal::ExeCompiler::RUNTIMES: bun, deno, node, quickjs, plus osascript on macOS only.

Known source issue: --verbose is registered twice in cli_options.rb (once with -v, once alone) with differing behaviour — the -v form prints the version and may exit. Treat the long form's behaviour as unspecified until this is fixed.

-r vs -q is the most common mix-up: -r affects the program you are compiling, -q affects the compiler process itself.

The set of valid -R values is platform-dependent — opal --help prints a different list on macOS, Linux, and Windows. An unrecognised name raises OptionParser::InvalidArgument:

$ opal -R bogus -e 'puts 1'
invalid argument: -R bogus (OptionParser::InvalidArgument)

Malformed --runner-options JSON raises an uncaught JSON::ParserError.

-L is compound: it sets lib_only, no_exit, compile, and skip_opal_require. It is the only place options[:compile] is assigned — -c does not set it.

--dce takes an optional argument, so opal --dce foo.rb consumes foo.rb as the option value rather than as the program file. Put --dce last, or use --dce=method. Values are not validated: --dce bogus silently yields [:bogus].

-D's help text says "(default: error)". This is wrong — Opal::Config.dynamic_require_severity defaults to :warning (lib/opal/config.rb:117). The help string is a known source bug.

--parse-comments, --await, and --use-strict have no Opal::Config counterpart; they are CLI-only compiler options. Everything else maps onto a config option — see config reference.

All of these were run against Opal 2.0.0dev.

Run a one-liner on Node:

$ opal -e 'puts "hi #{RUBY_ENGINE}"'
hi opal

Compile to stdout:

$ opal -c -e 'puts 1' | head -2
(function(global_object) {
  "use strict";

Compile to a file:

$ opal -c -e 'puts 1' -o app.js

Compile without the corelib (-O), producing a much smaller fragment:

$ opal -c -O -e 'puts 1' | head -2
Opal.queue(function(Opal) {/* Generated by Opal 2.0.0dev */
  var self = Opal.top, nil = Opal.nil;

Load a compiler plugin in the Ruby host, then compile:

$ opal -q json -e 'puts 2'
2

Compile a library bundle only:

$ opal -L -r my_library -o my_library.js

Serve a build over HTTP for browser testing:

$ opal -R server --server-port 4000 app.rb

Compile with a separate source map file:

$ opal -c app.rb -o app.js -P app.js.map

Build a standalone executable:

$ opal --compile-to-exe node app.rb

• Runners — every -R target
• Configuration reference — Opal::Config equivalents
• Compiler directives — magic comments
• Migrating to Opal 2.0