SYNOPSIS

pcbasic [program|package [output]] [OPTION] ...

POSITIONAL ARGUMENTS

Positional arguments must come before any options, must not start with
a dash -. Any positional arguments that follow options will be
ignored.

program
	If a .BAS program is specified as the first positional argument, it
	will be run. The --run, --load and --convert options override this
	behaviour.

package
	If a zipfile package or directory is specified as the first positional
	argument, any contained configuration file PCBASIC.INI will be loaded;
	usually, it will run a program file in the package. All other command-
	line options will override the package configuration file, note in
	particular the potential of the --run, --load and --convert options to
	alter the behaviour of the package.

output
	If a second positional argument is specified, it sets the output file
	for file format conversion. This argument is ignored unless the
	--convert option is given.

OPTIONS

--allow-code-poke[=True|=False]
	Allow programs to POKE into code memory.

--append[=True|=False]
	If used with --output=output_file, the output_file is appended to
	rather than overwritten.

--aspect=x,y
	Set the display aspect ratio to x:y. Only has an effect if combined
	with --interface=graphical.

-b
	Use the command-line interface. This is identical to --interface=cli.

--border=width
	Set the width of the screen border as a percentage from 0—100. The
	percentage refers to the total width of the borders on both sides as a
	fraction of the usable screen width. Only has an effect if combined
	with --interface=graphical.

--caption=title
	Set the title bar caption of the PC-BASIC window. Default title is PC-
	BASIC.

--cas1=type:value
	Attach a resource to the CAS1: cassette device. type:value can be

	WAV:wav_file
		Connect to the RIFF Wave file wav_file with data modulated in IBM PC
		cassette format.

	CAS:cas_file
		Connect to the PCE/PC-BASIC CAS tape image cas_file.

--cga-low[=True|=False]
	Use low-intensity palettes in CGA modes. Only has an effect if
	combined with --video={cga|cga_old|ega|vga}.

--codepage=codepage_id
	Load the specified codepage. The codepage determines which characters
	are associated to a given character byte or, in the case of double-
	byte codepages, two character bytes. The available codepages are
	stored in the codepage/ directory; by default, these are: 437 720 737
	775 806 850 851 852 853 855 856 857 858 860 861 862 863 864 865 866
	868 869 874 932 934 936 938 949 950 1258 alternativnyj armscii8a
	big5-2003 big5-hkscs georgian-academy georgian-ps iransystem iscii-as
	iscii-be iscii-de iscii-gu iscii-ka iscii-ma iscii-or iscii-pa iscii-
	ta iscii-te kamenicky koi8-r koi8-ru koi8-u mazovia mik osnovnoj
	pascii ruscii russup3 russup4ac russup4na viscii . See the list of
	codepages in the User's Guide for details.

--config=config_file
	Read a configuration file. The system default configuration is always
	read first, but any preset group of options in a configuration file
	replaces the whole equivalent default preset group.

--com1=type:value
	Attach a resource to the COM1: serial device. type:value can be one of
	the following.

	PORT:device_name
		Connect to a serial device. device_name can be a device name such as
		COM1 or /dev/ttyS0 or a number, where the first serial port is number
		0.

	SOCKET:host:socket
		Connect to a TCP socket on a remote or local host.

	RFC2217:host:socket
		Connect using the RFC2217 protocol to a TCP socket on a remote or
		local host.

	STDIO:[CRLF]
		Connect to standard I/O of the calling shell. If CRLF is specified,
		PC-BASIC replaces CR characters with LF on its output and LF with CR
		on its input. This is more intuitive on Unix shells. When using a Unix
		console, you should use stty -icanon to enable PC-BASIC to read input
		correctly.

	If this option is not specified, the COM1: device is unavailable.

--com2=type:value
	Attach a resource to the COM2: serial device. See --com1.

--convert={A|B|P}
	Convert program to one of the following formats:

	A
		Plain text

	B
		Tokenised

	P
		Protected

	If output is not specified, write to standard output. If program is
	not specified, use the argument of --run or --load. If none of those
	are given, read from standard input. Overrides --resume, --run and
	--load.

--mouse-clipboard[=True|=False]
	Enable clipboard operations with the mouse. If True (default), select
	text with the left mouse button to copy and paste with the middle
	mouse button.

--ctrl-c-break[=True|=False]
	If False, follow GW-BASIC behaviour where Ctrl+C breaks AUTO and INPUT
	but not program execution or LIST. If True, treat Ctrl+C exactly like
	Ctrl+Break and Ctrl+Scroll Lock when --interface=graphical. With
	--interface={text|cli}, Ctrl+C is always treated like Ctrl+Break.
	Default is True.

--current-device={CAS1|@|A|B ... |Z}
	Set the current device to the indicated PC-BASIC drive letter or CAS1
	for the cassette device. The device chosen should be mounted to an
	actual location using --mount (or --cas1 if the cassette device is
	chosen). Default is Z, with the Z: device mounted to your current
	drive.

--debug[=True|=False]
	Developer option - use only if you know what you're doing. Enable
	debugging extension.

--dimensions=x,y
	Set window dimensions to x by y pixels. This overrides
	--scaling=native and --aspect. Only has an effect if combined with
	--interface=graphical.

-d --double[=True|=False]
	Enable double-precision transcendental math functions. This is
	equivalent to the /d option in GW-BASIC.

-e=statement[:statement ...] --exec=statement[:statement ...]
	Execute BASIC statements. The statements are executed after loading
	any program but before entering into direct mode or running it.
	Multiple statements can be entered by separating them with colons :.
	These will be executed as if they were entered as separate statements,
	not as a single compound statement; even if statements such as GOTO
	can be included, the following statements will be executed. If a : is
	intended to be part of a statement, the statement must be quoted with
	single quotes '. If your calling shell interprets such quotes, you
	should properly escape them.

--extension=module_name[,module_name ... ]
	Developer option - use only if you know what you're doing. Load
	extension module(s).

--font=font_name[,font_name ... ]
	Use the specified fonts for the interface. The last fonts specified
	take precedence, previous ones are fallback. Default is
	unifont,univga,freedos (i.e. the freedos font has preference). The
	available fonts are stored in font/. By default, the following fonts
	are available: unifont univga freedos cga mda vga olivetti tandy1
	tandy2 . See the list of fonts in the User's Guide for details.

--fullscreen[=True|=False]
	Fullscreen mode. Only has an effect if combined with
	--interface=graphical.

-h --help
	Show a usage message and exit.

-i
	This option is ignored. It is included only for compatibility with GW-
	BASIC /i.

--input=input_file
	Retrieve keyboard input from input_file, except if KYBD: is read
	explicitly. Input from KYBD: files is always read from the keyboard,
	following GW-BASIC behaviour.

--interface=[none|cli|text|graphical]
	Choose the type of interface. Not all interfaces will be available on
	all systems. The following interface types may be available:

	none
		Filter for use with pipes. Also -n.

	cli
		Command-line interface. Also -b.

	text
		Text interface. Also -t.

	graphical
		Graphical interface.

	sdl2
		SDL2 graphical interface.

	pygame
		PyGame graphical interface.

	ansi
		ANSI text interface.

	curses
		NCurses text interface.

	The default is graphical.

-k=keystring --keys=keystring
	Insert the keystring into the keyboard buffer. keystring may contain
	escape codes such as \r for return, \n for line feed and \xXX to enter
	CHR$(&HXX). keystring may contain e-ASCII codes to indicate keypresses
	that do not have a regular character encoding. For example, \0\x0F
	indicates Shift+Tab.

-l=program --load=program
	Start in direct mode with the BASIC program loaded.

--logfile=log_file
	Write error and warning messages to log_file instead of stderr.

--lpt1=type:value
	Attach a resource to the LPT1: parallel device. type:value can be

	PRINTER:[printer_name][:trigger]
		Connect to a Windows, LPR or CUPS printer. If printer_name is not
		specified, the default printer is used. The printer is activated when
		a file open to it is closed, a program terminates or PC-BASIC exits.
		Note that, unlike LPT1:, printers connected to LPT2: or LPT3: do not
		get activated when a program terminates. If specified, trigger sets an
		additional trigger to activate the printer:

		line
			After every line break.

		page
			After every page break.

		close
			No additional trigger

		The default behaviour is that of close.

	FILE:file_name
		Connect to any file or device such as /dev/stdout on Unix or LPT1 on
		Windows.

	STDIO:[CRLF]
		Connect to standard output of the calling shell. If CRLF is specified,
		PC-BASIC replaces CR characters with LF on its output. This is more
		intuitive on Unix shells.

	PARPORT:port_number
		Connect to a Centronics parallel port, where port_number is 0 for the
		first parallel port, etc. PARPORT only works with physical parallel
		ports; for example, a Windows printer or other device mapped with NET
		USE LPT1: can only be attached with FILE:LPT1

	If this option is not specified, LPT1: is connected to the default
	printer.

--lpt2=type:value
	Attach a resource to the LPT2: parallel device. See --lpt1. If this
	option is not specified, LPT2: is unavailable.

--lpt3=type:value
	Attach a resource to the LPT3: parallel device. See --lpt1. If this
	option is not specified, LPT3: is unavailable.

--map-drives[=True|=False]
	On Windows, assign all Windows drive letters to PC-BASIC drive
	letters. On other systems, assign to:

	Z:
		the current working directory

	C:
		the filesystem root

	H:
		the user's home directory.

-f=number_of_files --max-files=number_of_files
	Set maximum number of open files to number_of_files. This is
	equivalent to the /f option in GW-BASIC. Default is 3.

-m=max_memory[,basic_memory_blocks] --max-
memory=max_memory[,basic_memory_blocks]
	Set the maximum size of the data memory segment to max_memory and the
	maximum size of the data memory available to BASIC to
	basic_memory_blocks*16. In PC-BASIC, the minimum of these values is
	simply the data memory size; the two values are allowed for
	compatibility with the /m option in GW-BASIC.

-s=record_length --max-reclen=record_length
	Set maximum record length for RANDOM files to record_length. Default
	is 128, maximum is 32767. This is equivalent to the /s option in GW-
	BASIC.

--monitor={rgb|composite|mono}
	Sets the monitor type to emulate. Available types are:

	rgb
		RGB colour monitor (default).

	composite
		Composite colour monitor.

	mono
		Monochrome monitor.

	On SCREEN 2 with --video={pcjr|tandy|cga|cga_old}, --monitor=composite
	enables (crude) colour artifacts.

--mono-tint=r,g,b
	Specify the monochrome tint as the red-green-blue values r,g,b, each
	in the range 0—255. Only has an effect if combined with
	--monitor=mono.

--mount=drive:path,[drive:path ... ]
	Assign the path path to drive letter drive:. The path can be absolute
	or relative. By default, Z: is assigned to the current working
	directory and no other drive letters are assigned.

-n
	Run PC-BASIC as a command-line filter. Same as --interface=none.

--nobox[=True|=False]
	Disable box-drawing recognition for double-byte character set code
	pages. By default, sequences of box-drawing characters are recognised
	by an algorithm that isn't as smart as it thinks it is, and displayed
	as box drawing rather than as DBCS characters. If --nobox is set, they
	will be displayed as DBCS.

--nokill[=True|=False]
	Allow BASIC to capture Alt+F4. Graphical interface only. By default,
	Alt+F4 is captured by most operating systems as a quit signal, and
	will terminate PC-BASIC. Set --nokill to allow BASIC to capture Alt+F4
	instead. This is useful if your program uses this key combination.

--output=output_file
	Send screen output to output_file, except if SCRN: is written to
	explicitly. Output to SCRN: files will always be shown on the screen,
	as in GW-BASIC.

--pcjr-term=terminal_program
	Set the terminal program run by the PCjr TERM command to
	terminal_program. This only has an effect with --syntax={pcjr|tandy}.

--peek=[seg:addr:val[,seg:addr:val ... ]]
	Define PEEK preset values. If defined, DEF SEG seg:? PEEK(addr) will
	return val.

--preset=option_block
	Load machine preset options. A preset option corresponds to a section
	defined in a config file by a name between square brackets, like

	[this] --preset=this will load all settings defined in that section.
	Available presets depend on your configuration file. See the list of
	default presets in the User's Guide.

-q --quit[=True|=False]
	Quit interpreter when execution stops. If combined with --run, PC-
	BASIC quits when the program ends. If set in direct mode, PC-BASIC
	quits after the first command is executed.

--reserved-memory=number_of_bytes
	Reserve number_of_bytes of memory at the bottom of the data segment.
	For compatibility with GW-BASIC. Default is 3429 bytes. Lowering this
	value makes more string and variable space available for use by
	programs.

--resume[=True|=False
	Resume from saved state. Overrides --run and --load.

-r=program --run=program
	Run the specified program. Overrides --load.

--scaling={smooth|crisp|native}
	Choose scaling method.

	smooth
		The display is smoothly scaled to the largest size that allows for the
		correct aspect ratio.

	crisp
		The display is scaled to the same size as with smooth, but without
		smoothing.

	native
		Scaling and aspect ratio are optimised for the display's native pixel
		size, without smoothing. --scaling=native overrides --aspect.

	Default is smooth. Only has an effect if combined with
	--interface=graphical.

-c=size --serial-buffer-size=size
	Set serial input buffer size. Default is 256. If set to 0, serial
	communications are disabled.

--shell=[shell-executable]
	Enable the SHELL statement to run the operating system command
	interpreter shell-executable. The executable shell-executable should
	support MS-DOS's COMMAND.COM calling conventions, in particular its /C
	switch. Example command interpreters are CMD.EXE on Windows and "wine
	cmd.exe" on Unix. If shell-executable is empty (as it is by default),
	the SHELL statement is disabled.

--sound-engine=[none|beep|portaudio]
	Choose the engine to use for audio output. If omitted, the default
	engine for the interface selected with --interface is chosen. Not all
	interfaces will be available on all systems.

	none
		Suppress sound output.

	beep
		Use the built-in speaker.

	portaudio
		Use the PortAudio sound generator.

--state=state_file
	Set the save-state file to state_file. Default is pcbasic.session in
	the Application Data directory.

--strict-hidden-lines[=True|=False]
	Disable listing and saving to plain text of lines beyond 65530, as in
	GW-BASIC. Use with care as this allows execution of hidden lines of
	code.

--strict-newline[=True|=False]
	Parse CR and LF in text and program files strictly like GW-BASIC. On
	Unix, you will need to convert your files to DOS text first if using
	this option.

--strict-protect[=True|=False]
	Disable listing and saving to plain text of protected files, as in GW-
	BASIC. Use with care as this allows execution of hidden lines of code.

--syntax={advanced|pcjr|tandy}
	Choose BASIC dialect. Available dialects are:

	advanced
		Microsoft GW-BASIC and IBM BASICA

	pcjr
		IBM PCjr Cartridge BASIC

	tandy
		Tandy 1000 GW-BASIC.

	Default is advanced.

-t
	Use text-based interface. Same as --interface=text.

--text-width={40|80}
	Set the number of columns in text mode at startup. Default is 80.

--utf8[=True|=False]
	Use UTF-8 for plain-text programs and redirected I/O. If True,
	programs stored as plain text will be converted from UTF-8 on LOAD and
	to UTF-8 on SAVE. If False, the PC-BASIC codepage will be used.

-v --version
	Print PC-BASIC version string and exit.

--video=card
	Set the video card to emulate. Available video cards:

	vga
		Video Graphics Array

	ega
		Enhanced Graphics Adapter

	cga
		Color/Graphics Adapter

	cga_old
		Color/Graphics Adapter (old version; affects composite)

	mda
		Monochrome Display Adapter

	hercules
		Hercules Graphics Adapter

	pcjr
		IBM PCjr graphics

	tandy
		Tandy 1000 graphics

	olivetti
		Olivetti M24 graphics

	Default is vga.

--video-memory=size
	Set the amount of emulated video memory available. This affects the
	number of video pages that can be used. On PCjr and Tandy, this can be
	changed at runtime through the CLEAR statement; at least 32768 needs
	to be available to enter SCREEN 5 and SCREEN 6. Default is 16384 or
	PCjr and Tandy and 262144 on other machine presets.

-w --wait[=True|=False]
	If True, PC-BASIC waits for a keystroke before closing the window on
	exit. Only works for --interface=graphical or --interface=text.
	Default is False.

GW-BASIC OPTIONS

GW-BASIC recognised a number of DOS-style command-line options on the
command-line when invoking it from DOS with a command like BASIC,
BASICA, or GWBASIC. These are matched by PC-BASIC with only minor
modifications, usually just replacing the forward slash / with a dash
-. The GW-BASIC syntax is shown here for reference only; only the
syntax with the dash works with PC-BASIC.

/d becomes -d
	Enable double-precision floating-point math functions.

/f:n becomes -f=n
	Set the maximum number of open files.

/s:n becomes -s=n
	Set the maximum record length for RANDOM files.

/c:n becomes -c=n
	Set the size of the receive buffer for COM devices.

/i:n becomes -i=n
	No effect.

/m:n,m becomes -m=n,m
	Set the highest memory location to n and maximum BASIC memory size to
	m*16 bytes.

>filename becomes --output=filename
	Write screen output to filename.

>>filename becomes --output=filename --append
	Append screen output to filename.

<filename becomes --input=filename
	Read keyboard input from filename.
