We're looking for a user researcher to understand the needs of developers and designers. Is this you or someone you know? Check out the post: https://mzl.la/2IGzdXS

Introduction to the JavaScript shell

The JavaScript shell (js) is a command-line program included in the SpiderMonkey source distribution. It is the JavaScript equivalent of Python's interactive prompt, the Lisp read-eval-print loop, or Ruby's irb. This article explains how to use the shell to experiment with JavaScript code and run JavaScript programs.

To get the SpiderMonkey JavaScript shell, see the SpiderMonkey Build Documentation or download a compiled binary for your platform from the Nightly Builds.

For a list of other JavaScript shells, see JavaScript shells.

Running the JavaScript shell

The shell offers two modes of operation. You can use it as an interactive shell, in which you type JavaScript code at a prompt and get instant gratification, which is handy for experimenting or testing new features. You can also pass in, on the command line, a JavaScript program file to run, in which case the program is run automatically.

If you want to run the shell in interactive mode, you can simply use the command:

js -i

If you'd like to run the JavaScript code in the file foo.js, you can use this command:

js -f foo.js

To run foo.js then drop into the interactive shell, do this:

js -f foo.js -i


Note: Because the JavaScript shell is used as a test environment for the JavaScript engine, the available options and built-in functions can change over time.

Command line options

There are a number of command line options you can specify to control the shell. These are summarized below. Be sure to use -h with your own jsshell to see if there is anything undocumented.

-b branchlimit
Sets the branch limit.
-c stackchunksize
Sets the stack chunk size.
Tells the shell to compile the program but not run it. This is a convenient way to quickly check for syntax errors in your program without actually running it.
-e script
Runs the specified script, which is a literal string containing the code to execute.
-f filename
Runs the JavaScript program specified by filename.
-g seconds
Sleep for seconds after starting the shell, f.e. to attach a debugger.
Enables interactive mode.
Enables trace jit.
Enables method jit.
If the first line of the file is "/usr/bin/env js -P", then the file content will be interpreted by the JavaScript engine.
This enables you to make a JavaScript file executable on unix and OS X machines.
Enables strict warning mode.
-S stacksize
Sets the maximum stack size.
-v version
Sets the version of JavaScript specified by version (e.g. 170 for JavaScript 1.7).
Enables warning messages.
Disables warning messages.
Enables E4X XML mode.

Environment options

There are some environment variables that can be set to alter js shell behavior.

Redirect stdout to file.
Redirect stderr to file.

Built-in functions

To make the JavaScript shell more useful, there are a number of built-in functions provided that you can use either from JavaScript programs or in interactive mode.

Note: This list is incomplete and overlaps with Shell global objects. See js/src/shell/js.cpp (around shell_functions) for more.


Returns the date and time at which the JavaScript shell was built.


Clears properties of the specified object. Calling clear() with no parameter clears everything so you can start with a clean slate.

Note: clear() with no parameters really clears everything. This includes all these built-in functions.

clone(function, [scope])

Clones the specified function object. If scope isn't specified, the new object's parent is the same as the original object's. Otherwise, the new object is placed in the scope of the object specified by scope.

countHeap([start[, kind]])

Added in SpiderMonkey 1.8 Count the number of live GC things in the heap, or things reachable from start when it is given and is not null. kind is either 'all' (default) to count all things or one of 'object', 'double', 'string', 'function', 'qname', 'namespace', 'xml' to count only things of that kind.

dumpHeap([fileName[, start[, toFind[, maxDepth[, toIgnore]]]]])

Added in SpiderMonkey 1.8 Dump the graph of all existing objects (or a specific interesting subgraph) to a file. For more information, see the C/C++ version of this function, JS_DumpHeap.

evalcx(string[, object])

Evaluates the JavaScript code in string. If object is specified, the code is executed in that object, treating it as a sandbox.

If string is empty and object is not specified, evalcx() returns a new object with eager standard classes.

If string is "lazy" and object is not specified, evalcx() returns a new object with lazy standard classes.

Note: evalcx() is only useful for people doing deep internal work on the JavaScript engine, for testing evalInSandbox-like environments in the shell.


Runs the garbage collector to free up memory.

gcparam(name[, value])

Added in SpiderMonkey 1.8 Read or configure garbage collector parameters.

The name must be one of the parameter keys (such as 'maxBytes', 'maxMallocBytes' or 'gcNumber').

If value is not specified, gcparam() returns the current value associated with GC parameter named name.

If value is specified, it must be convertable to a positive uint32; gcparam() sets GC parameter name to value.

For more information, see the C/C++ functions  JS_SetGCParameter and JS_SetGCParameter.


Added in SpiderMonkey 1.8 DEBUG only. Set the level of GC zeal, a debugging feature. This can be 0 for normal periodic garbage collection, 1 for very frequent GC, or 2 for extremely frequent GC. Anything other than 0 will make JavaScript run extremely slow but may help reveal or reproduce GC-related bugs. For more information, see the C/C++ version of this function, JS_SetGCZeal.


Returns the property descriptors for the specified object.


Returns the script line extent, which is the number of lines of code comprising the specified object.

help([command ...])

Displays brief help information about the specified commands, or about all available functions if none are specified.


Internalizes the specified string into the atom table. Every string has a unique identifier, called an atom. This system makes it easier to do comparisons between strings.

Note: This function is intended only for use when testing the JavaScript engine.

line2pc([function, ] line)

Returns the program counter value corresponding to the specified line of code. If function is specified, line is an offset into the specified function.

load(filename1 [filename])

Loads the JavaScript files with the specified names.

Note: For loading non-JavaScript files, use read().

options([option ...])

Lets you set or get options. If you specified options on the command line, the results of calling options will indicate which options you requested. You can also pass in new options to set.

If you start the shell with the command js -x, then the options() function will return xml. If you start the shell with no options, and decide you want to enable XML mode, you can do so by issuing the command:


The available options are:

Option Name Description
strict Strict mode is enabled.
werror Warnings should be treated as errors.
atline When atline is enabled, comments of the form //@line num set the number of the following line to num.
xml XML mode is enabled.

pc2line(function, [pc])

Returns the line number of the JavaScript code that corresponds to the first line of the specified function. If you specify a program counter offset into the function, the line number of the line of code containing that offset is returned.

print([expression ...])

Evaluates the expression(s) and displays the result(s) on stdout, separated by spaces (" ") and terminated by a newline ("\n").


Evaluates the expression and displays the result on stdout.


Exits the shell. status defaults to 0 if omitted.

read(filename[, type])

Reads and returns the contents of file. If type is "binary" returns an Uint8Array, otherwise returns an UTF-8 decoded string.


Reads a single line of input from stdin, returning it to the caller. You can use this to create interactive shell programs in JavaScript.


See Parser API.


Added in SpiderMonkey 1.8 Only in JS_THREADSAFE builds. Calls each function in fnArray without arguments, each in a different thread. When all threads have finished, this returns an array of the return values. Errors are not propagated; if any of the function calls fails, the corresponding element in the results array gets the exception object, if any, otherwise undefined.

Note: This function is intended only for use when testing the JavaScript engine.

seal(object[, deep])

Seals the specified object, or an object graph if deep is true. By sealing an object or object graph, you disable modification of those objects.


Added in SpiderMonkey 1.8 Only in JS_THREADSAFE builds. Sleep for dt seconds. Fractions of a second are supported. Returns true on success, false if the sleep was interrupted.

stackQuota([number]) Obsolete since JavaScript 1.8.6

Added in SpiderMonkey 1.8 Get or set the script stack quota.


Returns true if strings are encoded in UTF8 format; otherwise, returns false.


Performs UTF-8 tests. The mode parameter may be an integer from 1 to 4.

This is a debugging command that simply runs some checks on UTF-8 string handling, and isn't of general use, unless you're working on the JavaScript engine itself.


Throws an error from the JS_ReportError() function.

Note: This function is intended only for use when testing the JavaScript engine.

trap([function, [pc,]] expression)

Sets a trap at the specific point in the JavaScript code. When the bytecode at the offset specified by pc in the function function is about to be executed, the expression is evaluated.

This is a powerful debugging mechanism when used in concert with line2pc(). For example, if you want to display a message when line 6 of a function, doSomething() is executed, you can enter the following:

trap(doSomething, line2pc(doSomething, 6), "print('line 6!\n')");
Note: When a trap is set, the corresponding bytecode in the program is replaced with a trap bytecode until you use untrap() to remove the trap.

untrap(function [, pc])

Removes a trap from the specified function at the offset pc. If pc isn't specified, the trap is removed from the function's entry point.

This function has no effect if there is no trap at the specified location.


The version() function lets you get or set the JavaScript version number. This may be useful for gaining access to syntax only available in certain versions of JavaScript (for example, see Using JavaScript 1.7).

Debug functions

These built-in functions are only available in DEBUG builds.


Disassembles the JavaScript bytecode for the entire program, or for the specified function.

For example, if you enter the JavaScript function below:

function test() {
  var i = 3;

Then run the command dis(test);, you get this output:

00000:  uint16 3
00003:  setvar 0
00006:  pop
00007:  name "print"
00010:  pushobj
00011:  getvar 0
00014:  uint16 2
00017:  add
00018:  call 1
00021:  pop
00022:  stop

Source notes:
  0:     0 [   0] newline 
  1:     3 [   3] decl     offset 0
  2:     7 [   4] newline 
  3:    18 [  11] xdelta  
  4:    18 [   0] pcbase   offset 11


Disassembles the JavaScript bytecode for the entire program, or for the specified function, showing the source lines. This function only works with programs loaded from files, either using the -f flag on launching the shell, or by using the load() function.

If your program includes a function, doStuff(), like this:

function doStuff(input) {
	print("Enter a number: ");
	var n1 = readline();
	print("Enter another one: ");
	var n2 = readline();
	print("You entered " + n1 + " and " + n2 + "\n");

Calling dissrc(doStuff) function would give this output:

;-------------------------  10:         print("Enter a number: ");
00000:  10  name "print"
00003:  10  pushobj
00004:  10  string "Enter a number: "
00007:  10  call 1
00010:  10  pop
;-------------------------  11:         var n1 = readline();
00011:  11  name "readline"
00014:  11  pushobj
00015:  11  call 0
00018:  11  setvar 0
00021:  11  pop
;-------------------------  12:         print("Enter another one: ");
00022:  12  name "print"
00025:  12  pushobj
00026:  12  string "Enter another one: "
00029:  12  call 1
00032:  12  pop
;-------------------------  13:         var n2 = readline();
00033:  13  name "readline"
00036:  13  pushobj
00037:  13  call 0
00040:  13  setvar 1
00043:  13  pop
;-------------------------  14: 
;-------------------------  15:         print("You entered " + n1 + " and " + n2 + "\n");
00044:  15  name "print"
00047:  15  pushobj
00048:  15  string "You entered "
00051:  15  getvar 0
00054:  15  add
00055:  15  string " and "
00058:  15  add
00059:  15  getvar 1
00062:  15  add
00063:  15  string "\\n"
00066:  15  add
00067:  15  call 1
00070:  15  pop
00071:  15  stop

dumpheap(([fileName[, start[, toFind[, maxDepth[, toIgnore]]]]])

Dump GC information. This is a thin wrapper for JS_DumpHeap.


Enable extra-frequent GC, to help find GC hazards. zeal is an integer. The meaning is the same as for the parameter to JS_SetGCZeal.


Shows the source notes for the specified function. Source notes contain information that map the bytecode to the source code, which is used when decompiling the code, such as when using the dissrc() function.

stats([string ...])

Dumps statistics. Valid options are arena, atom, and global.

Option Description
arena Outputs the arena table.
atom Outputs the atom table.
global Outputs the global name table.

An arena is a large block of memory from which the JavaScript engine allocates sub-blocks in order to optimize performance; issuing a large number of malloc() calls for each individual block is inefficient, so the engine creates arenas, then uses an internal memory management system to allocate memory from within those. The arena table is a list of all the arenas that have been allocated by the shell. stats("arena") lets you inspect the arena table so that you can see how a test case uses arenas.

An atom is a unique identifier for a string. In order to optimize comparisons between strings, each string is given an atom. These atoms are stored in a hash table, which you can display using the command stats("atom").

stats("global") displays the global name table, which contains the names and information about each object in memory.


Enables or disables tracing mode. Pass true to enable tracing or false to turn it off. If you don't specify a parameter, tracing() returns the current setting.

Tip: This only works if you build JavaScript with JS_THREADED_INTERP turned off in the file jsinterp.c.

Document Tags and Contributors

Last updated by: Jorend,