---

11 Command-line options ¶

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

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

Type asy -licenses to see the license and third-party attribution information for Asymptote and its bundled components. Type asy -licenses=full or asy --licenses=full to print the full license texts (read from the installed licenses/ directory).