WolframScript

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:

file.wls
#!/usr/bin/env wolframscript
Print[2+2]
$ ./file.wls
4

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

file.wls
#!/usr/bin/env wolframscript -cloud
Print[2+2]
$ ./file.wls
4

A file that uses a command-line argument:

file.wls
#!/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:

file.wls
#!/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:

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

Additional Examples

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

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

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.

-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.

-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:

Default authentication folder:

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.

Tutorials

See Also

$ScriptCommandLine  $ScriptInputString  wolfram  mathematica  WolframKernel  "Package"  $IgnoreEOF  $BatchOutput