WolframScript

NAME

wolframscript — command-line script interpreter for the Wolfram Language

SYNOPSIS

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

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

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

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

DESCRIPTION

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

OPTIONS

    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

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

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

    -wstpserver [wstpserverbase] — Execute code in a WSTPServer specified by wstpserverbase. By default, wstpserverbase is port 31415.

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

    WSTPServer Options

    -wstpserver [wstpserverbase] — Execute code in a WSTPServer specified by wstpserverbase. By default, wstpserverbase is port 31415.

    -startprofile file — Create a WSTPServer kernel profile file or use an existing kernel profile file, saving the kernel ID.

    -continueprofile file — Continue with the kernel specified by the WSTPServer kernel profile file.

    -startprofile — Save WSTPServer kernel profile information in the current shell session.

    -continueprofile — Continue with the kernel specified by the WSTPServer kernel profile information saved in the current shell session.

    -kernelid id — Use the specific kernel managed by WSTPServer that has been assigned the ID id.

    -kernelpool pool — Use a kernel managed by WSTPServer in the pool pool.

    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.

    -entitlement id — Activate the kernel using an on-demand license entitlement ID.

    -listwstpservers — List the details of discovered WSTPServer services.

    -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

    DETAILS

    Wolfram Language Scripts

    The options specified on the #!wolframscript … line are ignored unless the script is launched by a Unix-style shell.

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

    WSTPServer Usage Details

    WolframScript can use DNS Service Discovery (DNS-SD) in order to find advertised WSTPServer services on the network.

    With the option -listwstpservers, WolframScript will print the WSTPServer services it discovers.

    With the option -wstpserver wstpserverbase, a wstpserverbase can be a link name of the form port[@hostname], the name of a WSTPServer service or a URL of the form wstp://hostname[:port][/kernelSpecifier]. By default, wstpserverbase is 31415. kernelSpecifier can be a kernel ID or a pool name. If kernelSpecifier is provided, WolframScript will use the specified kernel managed by WSTPServer. If kernelSpecifier is omitted, WolframScript will use the kernel provided by WSTPServer from the default pool.

    If the option -wstpserver wstpserverbase is not given, WolframScript will try to connect to WSTPServer at the default wstpserverbase. If that connection fails, WolframScript will try to connect to an auto-discovered WSTPServer service.

    WolframScript primarily uses profiles to interact with WSTPServer. Profiles are files that contain a description of a kernel managed by WSTPServer. The form this description must take is given in the section "PROFILE VARIABLES" that follows.

    If the option -startprofile file is given, WolframScript will create a profile at file. If file already exists, WolframScript will use the kernel described by file, but it will ignore any kernel ID in the file. WolframScript will save in file the ID of the exact kernel used for future use by -continueprofile file.

    If the option -startprofile is given, if file is not provided and if running from a shell, WolframScript will temporarily save in the current shell session the ID of the exact kernel used for future use by -continueprofile. This is also the behavior if -wstpserver is provided but -continueprofile is not. WolframScript will use the kernel provided by WSTPServer from the default kernel pool. The saved ID will expire in three hours from when -startprofile is given. If file is not provided, and if not running from a shell, WolframScript can fail.

    If the option -continueprofile file is given, WolframScript will continue from the kernel managed by WSTPServer specified by the profile file that has been previously given to -startprofile file. If file has not been previously provided to -startprofile, WolframScript will fail.

    If the option -continueprofile is given, if file is not provided and if running from a shell, WolframScript will continue from the kernel managed by WSTPServer that was previously used in the current shell session by -startprofile. If -startprofile has not been used in the current shell session, WolframScript will fail.

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

If a running WSTPServer is available on the network, evaluate the Wolfram Language code 2+2 in that WSTPServer:

$ wolframscript -wstpserver -code 2+2
4

Evaluate Wolfram Language code locally, escaping input for a Unix-style shell:

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

Evaluate Wolfram Language code locally, escaping input for the Windows cmd.exe 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 in a Unix-style shell:

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

A file to execute Wolfram Language code in a running WSTPServer in a Unix-style shell:

file.wls 
#!/usr/bin/env wolframscript -wstpserver
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 in a Unix-style shell:

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 14.1.0 Kernel for Mac OS X x86 (64‐bit)
Copyright 1988-2024 Wolfram Research, Inc.

In[1]:= 2+2

Out[1]= 4

In[2]:=

Run the Wolfram Language in an interactive REPL using a running WSTPServer:

$ wolframscript -wstpserver

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

Sign in to a different cloud account:

$ wolframscript -authenticate
Enter WolframID: example-user@wolfram.com
Password:

Success. Saving connection data.

Provide credentials without using a prompt:

$ wolframscript -username example-user@wolfram.com -password XXXXXX
Success. Saving connection data.

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 in a Unix-style shell:

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

Reverse the string on each line of an input file, writing the result to another file using cmd.exe on Windows:

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

Limit an evaluation using timeout:

$ wolframscript -code "Do[Print[i];Pause[1], {i,10}]" -timeout 3
1
2
3
$TimedOut

Use a specific character set for output in a Unix-style shell:

$ wolframscript -code 'Alphabet["Greek"]' -charset UTF8
{α, β, γ, δ, ε, ζ, η, θ, ι, κ, λ, μ, ν, ξ, ο, π, ρ, σ, τ, υ, φ, χ, ψ, ω}

Use a specific character set for output using cmd.exe on Windows:

> wolframscript -code Alphabet[\"Greek\"] -charset UTF8
{α, β, γ, δ, ε, ζ, η, θ, ι, κ, λ, μ, ν, ξ, ο, π, ρ, σ, τ, υ, φ, χ, ψ, ω}

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

file.wls 
#!/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 in a Unix-style shell:

file.wls 
#!/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
$ ./file.wls
Using -print All will each result
4

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

$ wolframscript -api 83aa0bc2-8e0c-4ef6-b314-48e0bf283196 -args n=5 -permissionskey thekey
25

Check the version of WolframScript:

$ wolframscript -version
WolframScript 1.2.0 for MacOSX-x86-64

Configure to use a particular WolframEngine:

$ wolframscript -config WOLFRAMSCRIPT_KERNELPATH=/Applications/Mathematica.app/MacOS/WolframKernel
Configured:WOLFRAMSCRIPT_KERNELPATH=/Applications/Mathematica.app/MacOS/WolframKernel

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_ENTITLEMENTID — An on-demand license entitlement ID to activate the kernel using.

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

WSTPSERVER PROFILE VARIABLES

WSTPSERVER — The WSTPServer base of the WSTPServer that manages the desired kernel.

POOL — The name of the pool of the desired kernel.

KERNELPATH — The kernel path of the desired kernel.

KEEPALIVE — The Boolean setting on whether to close the kernel on unbridge of the desired kernel.

RESERVEONDISCONNECT — The Boolean setting on whether to reserve the kernel on unbridge of the desired kernel.

If a profile variable is not provided, WolframScript will not select for a kernel managed by WSTPServer according to that profile variable.