NAME

wolframscript — command-line script interpreter for the Wolfram Language

SYNOPSIS

wolframscript -code code [-cloud [cloudbase] | -local [kernelpath]] [arg1 …]

wolframscript -file file|url [-cloud [cloudbase] | -local [kernelpath]] [arg1 …]

wolframscript -api url|uuid|file [-cloud [cloudbase] | -local [kernelpath]] [-args key=value …]

wolframscript -function code [-cloud [cloudbase] | -local [-kernelpath]] [-signature type …] [-args values …]

DESCRIPTION

WolframScript runs Wolfram Language code, functions, and deployed APIs, either locally or in the cloud, allowing input from standard input, command-line arguments, files, URLs, etc.

EXAMPLES

Code from Command Line

Evaluate the Wolfram Language code 2+2 on a local Wolfram Engine:

$ wolframscript -code 2+2
4

Evaluate the Wolfram Language code 2+2 in the Wolfram Cloud, prompting for authentication as needed:

$ wolframscript -cloud -code 2+2
4

Evaluate Wolfram Language code locally, escaping input for the shell:

$ wolframscript -code 'StringReverse["hello"]'
olleh

Evaluate code and put the results in a file:

$ wolframscript -code 'Graphics3D[Sphere[ ]]' -format PNG > file.png

Code from File

Evaluate Wolfram Language code from a file, returning the last result generated:

$ wolframscript -file test.wl
12345

Take code from a local file, but run it in the cloud:

$ wolframscript -cloud -file test.wl
12345

Script Files

A file set up to execute Wolfram Language code locally:

#!/usr/bin/env wolframscript
Print[2+2]

$ ./file.wls
4

A file to execute Wolfram Language code in the Wolfram Cloud:

#!/usr/bin/env wolframscript -cloud
Print[2+2]

$ ./file.wls
4

A file that uses a command-line argument:

#!/usr/bin/env wolframscript
Print[ToExpression[$ScriptCommandLine[[2]]]^2]

$ ./file.wls 5
25

A file giving a function whose arguments come from the command line:

#!/usr/bin/env wolframscript -function -signature City City
GeoDistance[#1, #2]&

$ ./file.wls "New York" London
Quantity[3453.7070027090986, Miles]

Interactive Operation

Run the Wolfram Language in an interactive REPL:

$ wolframscript
Wolfram Language 11.0.0 for Microsoft Windows (64-bit)
Copyright 1988-2016 Wolfram Research, Inc.

In[1]:= 2+2

Out[1]= 4

In[2]:= 

APIs

Run a cloud API:

$ wolframscript -api https://wolfr.am/bNvKWq2U -args x=1 y=2
3

Get the code for an API from the cloud, but run the API locally:

Additional Examples

Sign in to a different cloud account:

Provide credentials without using a prompt:

Disconnect from the cloud, clearing connection information:

$ wolframscript -disconnect

Reverse the string on each line of an input file, writing the result to another file:

$ wolframscript -code 'StringReverse[$ScriptInputString]' -linewise < file1 > file2 

Limit an evaluation using timeout:

Use a specific character set for output:

Use the options -print and -format in a script to generate an image:

#!/usr/bin/env wolframscript -print -format PNG
ListLinePlot[RandomFunction[WienerProcess[],{0,10,0.01},10]]

$ ./file.wls > plot.png

Print each result generated during the execution of a script using the -print All option:

#!/usr/bin/env wolframscript -print All
"Using -print All print will each result"
a = 2+2; (* This line won't print because the ; suppresses output *)
a

Create an API protected by a PermissionsKey, and pass the key to WolframScript to access it:

In[1]:=

Out[1]=

Check the version of WolframScript:

Configure to use a particular WolframEngine:

OPTIONS

Code Options

-c|-code code — Give Wolfram Language code to execute.

-f|-file file — Give a file containing Wolfram Language code to execute.

-api url|uuid|file — Use an API at the specified URL, or coming from a cloud or local object with the specified UUID, or coming from the specified local file. Use arguments key=value ….

-fun|-function code [-s|-signature type …] [-args|-- value …] — Use a function whose arguments are the strings value …, interpreted as being of types type …. If no signature is given, all arguments are assumed to be strings. Signature types can be any of $InterpreterTypes.

Execution Options

-o|-cloud [cloudbase] — Execute code in the cloud, using the specified cloud base. By default, cloudbase is https://wolframcloud.com.

-l|-local [kernelpath] — Execute code locally, using the specified path to the Wolfram Engine kernel. By default, kernelpath uses the most recent version of the Wolfram Language found on the local system.

-format type — Specify the format in which to give output. Any format understood by Export can be used.

-charset encoding — Use encoding for output. Encodings can be None, to output raw bytes, or any entry in $CharacterEncodings except "Unicode". The default is to infer the value from the terminal's language settings.

-linewise — Execute code on each line of standard input that is read.

-print [all] — When running a script, print the result from executing the last line of the script, or each line if all is given.

-timeout seconds [value] — Specify the number of seconds to allow for execution. Return value if the time is exceeded.

-v|-verbose — Print additional information during execution.

Utility Options

-h|-help — Print help text.

-version — Print WolframScript version.

-auth|-authenticate [wolframid [password]] [-cloud cloudbase] — Authenticate with the cloud, specifying a particular Wolfram ID and password, and prompting if they are not given. Different authentication can be specified for different clouds.

-username [wolframid] — Specify Wolfram ID used to authenticate with the cloud.

-password [password] — Specify password used to authenticate with the cloud.

-permissionskey key — Use a permissions key to access a cloud resource.

-config|-configure [key=value …] — Configure WolframScript by specifying values for particular configuration variables keys.

-disconnect [-cloud cloudbase] — Disconnect from the cloud, removing authentication information.

DETAILS

Wolfram Language Scripts

All standard options can be used in #!wolframscript scripts.

With #!wolframscript -function …, each argument to the function can be given on the script command line.

With #!wolframscript -api …, the parameters of the API can be given on the script command line in the form -key value ….

The exit code from executing a script can be specified using Exit[code].

Without -print, no output will be sent to stdout unless this is explicitly done using Print[expr].

With the option -print, the result from the last line in the script is sent to stdout.

With the option -print all, results from each line in the script are sent to stdout when they are generated.

The -linewise option can be used to run the script multiple times, taking a single line of stdin as input each time.

Command-Line Input

Input given to a script on standard input can be accessed in Wolfram Language code using $ScriptInputString.

Arguments given on the command line can be accessed using $ScriptCommandLine.

Output Formatting

The default setting for TotalWidth is Infinity.

API Parameters

If an API supports extended parameters such as x-url, x-format, and _timeout, these can be given in wolframscript -api.

Code Location

In wolframscript -api uuid, LocalObject["uuid"] is used if it exists, otherwise CloudObject["uuid"].

FILES

Default configuration file:

• 	%APPDATA%∖Wolfram∖WolframScript∖WolframScript.conf	Windows
  	~/Library/Application Support/Wolfram/WolframScript/WolframScript.conf	Macintosh
  	~/.config/Wolfram/WolframScript/WolframScript.conf	Unix

Default authentication folder:

• 	%LOCALAPPDATA%∖Wolfram∖WolframScript∖	Windows
  	~/Library/Caches/Wolfram/WolframScript/	Macintosh
  	~/.cache/Wolfram/WolframScript/	Unix

WOLFRAM LANGUAGE VARIABLES

The following variables are set when WolframScript begins execution.

$CommandLine — A list of strings giving the complete command line used.

$ScriptCommandLine — A list of command-line arguments intended for the script being run. These come after options given with -option.

$ScriptInputString — A string giving input supplied to the script through standard input. The option -linewise loads this variable with one line of standard input for each iteration of the script.

ENVIRONMENT VARIABLES

WOLFRAMSCRIPT_AUTHENTICATIONPATH — The folder storing authentication information.

WOLFRAMSCRIPT_CONFIGURATIONPATH — The file storing persistent configuration information.

WOLFRAMSCRIPT_CLOUDBASE — The default cloud base to use in WolframScript.

WOLFRAMSCRIPT_KERNELPATH — The path to the default local Wolfram Engine kernel executable.

CONFIGURATION VARIABLES

WOLFRAMSCRIPT_AUTHENTICATIONPATH — The path to files storing authentication information if the same-named environment variable is not set.

WOLFRAMSCRIPT_CLOUDBASE — The default cloud base to use in WolframScript if the same-named environment variable is not set.

WOLFRAMSCRIPT_KERNELPATH — The path to the default local Wolfram Engine kernel executable if the same-named environment variable is not set.