9 Command-line options

Type asy -h to see the full list of command-line options supported by Asymptote:

Usage: ../asy [options] [file ...]

Options (negate boolean options by replacing - with -no): 

-GPUblockSize n        Compute shader block size [8]
-GPUcompress           Compress GPU transparent fragment counts [false]
-GPUindexing           Compute indexing partial sums on GPU [true]
-GPUinterlock          Use fragment shader interlock [true]
-GPUlocalSize n        Compute shader local size [256]
-V,-View               View output; command-line only
-absolute              Use absolute WebGL dimensions [false]
-a,-align C|B|T|Z      Center, Bottom, Top, or Zero page alignment [C]
-aligndir pair         Directional page alignment (overrides align) [(0,0)]
-animating             [false]
-antialias n           Antialiasing width for rasterized output [2]
-auto3D                Automatically activate 3D scene [true]
-autobillboard         3D labels always face viewer by default [true]
-autoimport str        Module to automatically import
-autoplain             Enable automatic importing of plain [true]
-autoplay              Autoplay 3D animations [false]
-autorotate            Enable automatic PDF page rotation [false]
-axes3                 Show 3D axes in PDF output [true]
-batchMask             Mask fpu exceptions in batch mode [false]
-batchView             View output in batch mode [false]
-bw                    Convert all colors to black and white false
-cd directory          Set current directory; command-line only
-cmyk                  Convert rgb colors to cmyk false
-c,-command str        Command to autoexecute
-compress              Compress images in PDF output [true]
-convertOptions str    []
-d,-debug              Enable debugging messages and traceback [false]
-devicepixelratio n    Ratio of physical to logical pixels [1]
-digits n              Default output file precision [7]
-dvipsOptions str      []
-dvisvgmMultipleFiles  dvisvgm supports multiple files [true]
-dvisvgmOptions str    [--optimize]
-embed                 Embed rendered preview image [true]
-e,-environment        Show summary of environment settings; command-line only
-exitonEOF             Exit interactive mode on EOF [true]
-fitscreen             Fit rendered image to screen [true]
-framerate frames/s    Animation speed [30]
-glOptions str         []
-globalread            Allow read from other directory true
-globalwrite           Allow write to other directory false
-gray                  Convert all colors to grayscale false
-gsOptions str         []
-h,-help               Show summary of options; command-line only
-historylines n        Retain n lines of history [1000]
-htmlviewerOptions str
                       []
-hyperrefOptions str   [setpagesize=false,unicode,pdfborder=0 0 0]
-ibl                   Enable environment map image-based lighting [false]
-iconify               Iconify rendering window [false]
-image str             Environment image name [snowyField]
-imageDir str          Environment image library directory [ibl]
-inlineimage           Generate inline embedded image [false]
-inlinetex             Generate inline TeX code [false]
-inpipe n              Input pipe [-1]
-interactiveMask       Mask fpu exceptions in interactive mode [true]
-interactiveView       View output in interactive mode [true]
-interactiveWrite      Write expressions entered at the prompt to stdout [true]
-interrupt             [false]
-k,-keep               Keep intermediate files [false]
-keepaux               Keep intermediate LaTeX .aux files [false]
-level n               Postscript level [3]
-l,-listvariables      List available global functions and variables [false]
-localhistory          Use a local interactive history file [false]
-loop                  Loop 3D animations [false]
-lossy                 Use single precision for V3D reals [false]
-lsp                   Interactive mode for the Language Server Protocol [false]
-m,-mask               Mask fpu exceptions; command-line only
-maxtile pair          Maximum rendering tile size [(1024,768)]
-maxviewport pair      Maximum viewport size [(0,0)]
-multiline             Input code over multiple lines at the prompt [false]
-multipleView          View output from multiple batch-mode files [false]
-multisample n         Multisampling width for screen images [4]
-offline               Produce offline html files [false]
-O,-offset pair        PostScript offset [(0,0)]
-f,-outformat format   Convert each output file to specified format
-o,-outname name       Alternative output directory/file prefix
-outpipe n             Output pipe [-1]
-paperheight bp        Default page height [0]
-paperwidth bp         Default page width [0]
-p,-parseonly          Parse file [false]
-pdfreload             Automatically reload document in pdfviewer [false]
-pdfreloadOptions str  []
-pdfreloaddelay usec   Delay before attempting initial pdf reload [750000]
-pdfviewerOptions str  []
-position pair         Initial 3D rendering screen position [(0,0)]
-prc                   Embed 3D PRC graphics in PDF output [false]
-prerender resolution  Prerender V3D objects (0 implies vector output) [0]
-prompt str            Prompt [> ]
-prompt2 str           Continuation prompt for multiline input  [..]
-psviewerOptions str   []
-q,-quiet              Suppress welcome text and noninteractive stdout [false]
-render n              Render 3D graphics using n pixels per bp (-1=auto) [-1]
-resizestep step       Resize step [1.2]
-reverse               reverse 3D animations [false]
-rgb                   Convert cmyk colors to rgb false
-safe                  Disable system call true
-scroll n              Scroll standard output n lines at a time [0]
-shiftHoldDistance n   WebGL touch screen distance limit for shift mode [20]
-shiftWaitTime ms      WebGL touch screen shift mode delay [200]
-spinstep deg/s        Spin speed [60]
-svgemulation          Emulate unimplemented SVG shading [true]
-tabcompletion         Interactive prompt auto-completion [true]
-tex engine            latex|pdflatex|xelatex|lualatex|tex|pdftex|luatex|context|none [latex]
-thick                 Render thick 3D lines [true]
-thin                  Render thin 3D lines [true]
-threads               Use POSIX threads for 3D rendering [true]
-toolbar               Show 3D toolbar in PDF output [true]
-s,-translate          Show translated virtual machine code [false]
-twice                 Run LaTeX twice (to resolve references) [false]
-twosided              Use two-sided 3D lighting model for rendering [true]
-u,-user str           General purpose user string
-v3d                   Embed 3D V3D graphics in PDF output [false]
-v,-verbose            Increase verbosity level (can specify multiple times) 0
-version               Show version; command-line only
-vibrateTime ms        WebGL shift mode vibrate duration [25]
-viewportmargin pair   Horizontal and vertical 3D viewport margin [(0.5,0.5)]
-wait                  Wait for child processes to finish before exiting [false]
-warn str              Enable warning; command-line only
-webgl2                Use webgl2 if available [false]
-where                 Show where listed variables are declared [false]
-wsl                   Run asy under the Windows Subsystem for Linux [false]
-xasy                  Interactive mode for xasy [false]
-zoomPinchCap limit    WebGL maximum zoom pinch [100]
-zoomPinchFactor n     WebGL zoom pinch sensitivity [10]
-zoomfactor factor     Zoom step factor [1.05]
-zoomstep step         Mouse motion zoom step [0.1]

All boolean options can be negated by prepending no to the option name.

If no arguments are given, Asymptote runs in interactive mode (see Interactive mode). In this case, the default output file is out.eps.

If - is given as the file argument, Asymptote reads from standard input.

If multiple files are specified, they are treated as separate Asymptote runs.

If the string autoimport is nonempty, a module with this name is automatically imported for each run as the final step in loading module plain.

Default option values may be entered as Asymptote code in a configuration file named config.asy (or the file specified by the environment variable ASYMPTOTE_CONFIG or -config option). Asymptote will look for this file in its usual search path (see Search paths). Typically the configuration file is placed in the .asy directory in the user’s home directory (%USERPROFILE%\.asy under MSDOS). Configuration variables are accessed using the long form of the option names:

import settings;
outformat="pdf";
batchView=false;
interactiveView=true;
batchMask=false;
interactiveMask=true;

Command-line options override these defaults. Most configuration variables may also be changed at runtime. The advanced configuration variables dvipsOptions, hyperrefOptions, convertOptions, gsOptions, htmlviewerOptions, psviewerOptions, pdfviewerOptions, pdfreloadOptions, glOptions, and dvisvgmOptions allow specialized options to be passed as a string to the respective applications or libraries. The default value of hyperrefOptions is setpagesize=false,unicode,pdfborder=0 0 0.

If you insert

import plain;
settings.autoplain=true;

at the beginning of the configuration file, it can contain arbitrary Asymptote code.

The default output format is EPS for the (default) latex and tex tex engine and PDF for the pdflatex, xelatex, context, luatex, and lualatex tex engines. Alternative output formats may be produced using the -f option (or outformat setting).

To produce SVG output, you will need dvisvgm (version 3.2.1 or later) from https://dvisvgm.de, which can display SVG output (used by the xasy editor) for embedded EPS, PDF, PNG, and JPEG images included with the graphic() function. The generated output is optimized with the default setting settings.dvisvgmOptions="--optimize".

Asymptote can also produce any output format supported by the ImageMagick magick program (version 7 or later. The optional setting -render n requests an output resolution of n pixels per bp. Antialiasing is controlled by the parameter antialias, which by default specifies a sampling width of 2 pixels. To give other options to magick, use the convertOptions setting or call magick convert manually. This example emulates how Asymptote produces antialiased tiff output at one pixel per bp:

asy -o - venn | magick convert -alpha Off -density 144x144 -geometry 50%x eps:- venn.tiff

If the option -nosafe is given, Asymptote runs in unsafe mode. This enables the int system(string s) and int system(string[] s) calls, allowing one to execute arbitrary shell commands. The default mode, -safe, disables this call.

A PostScript offset may be specified as a pair (in bp units) with the -O option:

asy -O 0,0 file

The default offset is zero. The pair aligndir specifies an optional direction on the boundary of the page (mapped to the rectangle [-1,1]\times[-1,1]) to which the picture should be aligned; the default value (0,0) species center alignment.

The -c (command) option may be used to execute arbitrary Asymptote code on the command line as a string. It is not necessary to terminate the string with a semicolon. Multiple -c options are executed in the order they are given. For example

asy -c 2+2 -c "sin(1)" -c "size(100); draw(unitsquare)"

produces the output

4
0.841470984807897

and draws a unitsquare of size 100.

The -u (user) option may be used to specify arbitrary Asymptote settings on the command line as a string. It is not necessary to terminate the string with a semicolon. Multiple -u options are executed in the order they are given. Command-line code like -u x=sqrt(2) can be executed within a module like this:

real x;
usersetting();
write(x);

When the -l (listvariables) option is used with file arguments, only global functions and variables defined in the specified file(s) are listed.

Additional debugging output is produced with each additional -v option:

-v

Display top-level module and final output file names.

-vv

Also display imported and included module names and final LaTeX and dvips processing information.

-vvv

Also output LaTeX bidirectional pipe diagnostics.

-vvvv

Also output knot guide solver diagnostics.

-vvvvv

Also output Asymptote traceback diagnostics.