www.riscos.com Technical Support:
RISC OS 3 User Guide


RISC OS 3.7 User Guide

Appendix A: The command line

Usually you will use the RISC OS desktop for almost all of your computing tasks. However occasionally you may need to use the command line.

The command line is very different from the desktop. Gone are the windows, icons and menus. These are replaced by a set of single line commands that always start with a star, the Star Commands (known as *commands).

All the commands are described, in alphabetical order, in the file StarComms in the Tutorials directory. Alternatively, see Getting Help later in this chapter.

Using the command line you can run scripts. Scripts are small programs (which you usually write in Edit) that help you control the computer. The command line is also used to issue operating system commands from BASIC.

This chapter gives you an introduction to the command line. The RISC OS 3 Programmer's Reference Manual expands on all the information given in this chapter.

Accessing the command line

The following options on the Task manager icon bar menu give you access to the command line.

New task

To start a new task, move to the New task submenu of the Task menu. This produces a box into which you can type any Command Line command. If the command causes a task that is not a desktop application to run, any output from the task will be displayed in a new window; other tasks will be suspended until this task has completed. If the task is a desktop application, starting it from the New task submenu is equivalent to double-clicking on the application.

* Commands

By choosing *Commands from the Task menu, you can enter Command Line Mode. A * prompt appears at the bottom of the screen, and you can enter operating system commands. To return to the desktop, press Return at a * prompt without entering any other characters on the line. Pressing F12 is equivalent to choosing * Commands from the Task Manager menu.

Task window

This option allows you to use Command Line mode in a window. If you ever have to use the command line for more than a single command, this is the best way to do it. To open the window, choose Task window from the icon bar menu. You can have more than one Task window open. When you open a task window, you will see the * prompt. You can now enter operating system commands in the window.


Clicking on Exit causes the desktop and all tasks to be closed down and replaced by the command line. You can restart the desktop by typing desktop at the * prompt, and then pressing Return.

Command line mode

The star (*) prompt indicates that you are in command line mode and that the computer is expecting a command to be typed. Note that command line mode is sometimes called Supervisor mode (for example, when the machine starts up in command line mode).

The commands in this guide are always preceded by a star. The star is provided as a prompt in command line mode, so you do not have to type it (though it does not matter if you do, any extra stars are ignored). However, if you type a * Command following some other prompt (at the BASIC > prompt, for example), you must precede it with a star so that the computer knows how to interpret what follows.

Pausing on a full screen

If you are using the command line mode and you want to display a large amount of information you can set the system to pause at each full screen. Do this by typing Ctrl-N. Use the Shift key to scroll through the screenfulls. Ctrl-O removes this feature; the display no longer pauses. This does not apply to Task windows.

Starting BASIC from the command line

Enter BASIC by typing *BASIC from the command line. The prompt will change from * to >. To confirm that you are in BASIC, type in the following one-line program (must be typed using capital letters).

  FOR N=1 TO 20: PRINT "HELLO": NEXT N   (press Return)

This will cause the word HELLO to be printed twenty times. Leave BASIC by typing QUIT or *Quit.

For information on using BASIC see Appendix 9:BBC BASIC.

The BBC BASIC Reference Manual is the complete reference guide for the BBC BASIC language.

Using the Task window

The Task window allows you to use the command line within a window. To open a Task window, choose Task window from the Task manager icon bar menu. When you open a Task window, you will see a * prompt. You can now enter commands in the window just as if you were using the command line itself. Like any other application, you can have more than one Task window at the same time.

The major advantages in entering commands in a Task window instead of at the command line prompt are;

You can change this by unlinking the window. In this case, anything you type in alters the contents of the window in the same way as any other Edit window, even while a task is running. Keyboard short-cuts only operate if the window is unlinked.

You can also supply input to a task window by selecting some text from any text file and choosing TaskInput from the task window menu.

You cannot use graphics in a task window. If the Ignore Ctl option is not chosen, the output of any commands that use graphics will appear as screen control codes.

The Task window is controlled by Edit, so don't be surprised if you see the Edit icon on your icon bar.

The menu for a Task window contains the following options.
    Kill stops and destroys the task running in the window. Reconnect starts a new task in the window, allocating memory from the Task manager's Next slot.
  • Suspend temporarily halts the task running in the window. Resume restarts a suspended task.
  • Unlink prevents the sending of typed-in characters to the task. Instead, they are processed as if the task window were a normal Edit text window. Link reverses the effect of Unlink.
  • TaskInput reads task input from the currently selected block.
  • Ignore Ctl, when selected, prevents any control characters generated by the program from being sent to the screen.
  • Edit leads to the normal Edit menu. Although this makes available most of Edit's features, you cannot use facilities such as the cursor keys or keys such as Page Up and Home while you are using a task window. If you want to use Edit's keyboard short-cut features, Unlink the window first.

Memory requirements

The amount of memory that the Task window uses is controlled by the size of the Next slot in the Task manager window. If you need a lot of memory for the Task manager, you can increase the Next slot size.

Some guidelines and suggestions for using Task windows

To use a Task window, you will need to be familiar with command line mode. However you will also find that nearly all of the commands that affect the configuration of the desktop can also be performed using the application !Boot and the Task manager window Tasks.

Here are a few commands.

The command *Spool should not be used from a task window. Because its effect is to write everything that appears on the screen to the spool file, using *Spool from the desktop will produce unusable files full of screen control characters. There is, in any case, no point in using *Spool, since the output from the task appears in the window, and can be saved using Edit as normal.

When you run a command in a Task window, the computer divides its time between the Task window and other activities running in the desktop. Note that some time-consuming commands may prevent access to the filing system until the command is complete.

Note 1: Command line notions such as 'current directory' become relevant when you are using Task Windows.

Note 2: Using the *Copy command in a task window may lead to Filer error. Only use *Copy from the command line prompt (press F12).

Note 3: Do not close a Task window while a command-line process is still running, or initiate one with little memory available, as internal errors may result.

All of these commands are described in detail in the file StarComms in the Tutorials directory.

Getting Help

The command *Help gives brief information about each command in the operating system. *Help keyword displays a brief explanation of the keyword and, if the keyword is a command name, the syntax of the command.

If you are not sure about the name of a command;

The usual use of *Help is to confirm that a command is appropriate for the job required, and to check on its syntax (the number, type and ordering of parameters that the command requires).

When you issue the *Help command at the normal command line prompt, 'paged mode' is switched on: the computer displays a screenful of text, then waits until you press Shift before moving on (in a Task window, you just scroll).

The specification of the keyword can include abbreviations to allow groups of commands to be specified. For example,

    *help con.

produces information on *Configure and *Continue. You can also use this to establish the current abbreviation for a command. Since RISC OS uses the first command it finds that matches an abbreviation, typing *Con. is equivalent to *Configure. For the *Continue command, the minimum abbreviation must distinguish it from *Configure, and is therefore *Cont. These abbreviations may change as new commands are added.

Using the command line

You will find many hints in the following sections:

Command line syntax

The interface to the command line is built into the RISC OS operating system and processes valid commands sent as text strings. The text string is normally terminated by Return.

The syntax of each command in the following chapters is described in a standard way, with examples of its use where these are helpful. The symbols used in syntax descriptions are:

<value> indicate that an actual value must be substituted. For example, <filename> means that you must supply an actual filename.

[...] indicate that the item enclosed in the square brackets is optional.

| indicates alternatives. For example, 0 | 1 means that the value 0 or 1 must be supplied.

What are parameters?

RISC OS commands are sometimes followed by one or more parameters which tell the computer how you want the command to be modified.

In the following descriptions, the parameters are in italics. You can leave spaces only between parameters, since otherwise the operating system cannot tell where you want one parameter to end and the next to begin.

Command line parameters may be optional. In this case they are shown in the syntax within square brackets. Often, when a parameter is specified as optional, the operating system will supply a default value; the value of this is specified for each command.

Numeric parameters

Some commands have one or more numeric parameters. These are interpreted as decimal by default (unless the description of the command specifies otherwise), but it is possible to express them in any base by prefacing the parameter itself with the base followed by an underscore, as in the following examples:

  *Eval 2_1010101   *Eval 16_FFF   similarly, returns the value 4095.

An alternative form for hexadecimal uses the & sign to signify base 16.

  *Eval &FFF

Decimal and hexadecimal are likely to be the most useful bases.


It is useful in many command line operations to specify objects using 'wildcards'. There are two wildcards.

  *   stands for zero or more characters
  #   stands for a single character


  he*   would stand for he, help, hello, or hencoop
  he*p   would stand for help or hencoop
  he##   would stand for help, hens or head, but not hen or health

Checks on the command

Before a command is executed, the command line interface carries out a certain amount of pre-processing on the line:

Full details of this checking are given in the RISC OS Programmer's Reference Manual.

File redirection

A powerful feature of RISC OS is the ability to redirect input or output streams (or both) for the duration of the command. By default, output is directed to the screen, but it may be convenient to redirect the output stream to a file so that you can examine it later in more detail, or process it further.

The format of a redirection is;

  <command> { <redirection spec> }

where the <redirection spec> is at least one of;

  > <filename> : output goes to filename
  < <filename : input read from filename
  >> <filename : output is appended to filename.

Note the following.


System devices

The operating system contains a number of useful system devices, which behave like files in some ways. You can use them anywhere you would normally use a file name as a source of input, or as a destination for output. These include:

System devices suitable for input

System devices suitable for output

These system devices can be useful with commands such as *Copy, and the redirection operators (> and <):

The system device null is useful to suppress unwanted output from a command script or program.

  *myprogram { > null: } Runs myprogram with no output

The most useful system devices for the general user are likely to be printer: and netprint:

!Run and !Boot files within applications

If you Shift-double-click on an application you'll see a !Run file (it has the file type Obey). An application's !Run file is obeyed whenever you start the application. This file sets up the application's environment, loads any resources it requires and then starts the application code (often called !Runimage).

The application also contains a !Boot file, this is used when the application is first 'seen'. This occurs when the directory containing the application is displayed on the screen. The !Boot file sets up the application sprite used in the directory display.

Using !Draw as an example

Most !Boot and !Run files have lines containing Set commands. For example, !Draw sets up variables that include a RunType and a PrintType for the normal DrawFile file type &AFF.

Draw also sets up a variable called Draw$Dir which sets up the computer to remember where the Draw application is on the computer. It uses another variable called Obey$Dir, this contains the path of the directory in which the current obey file is running.

You will find all these variables explained in greater detail later in this chapter.

What is a module?

A module is a piece of software that is loaded into memory. A section of memory is reserved for use by modules and is known as the RMA (Relocatable Module Area).

If you look at the !Run file of !Draw you'll see some RMEnsure commands are used these particular commands make RISC OS check the named module is present in the RMA.

System variables

Introducing system variables

System variables are used by RISC OS to store settings that control the behaviour of the computer. For example, they store how you like the time and date to be printed, how you want the *Copy command to work, and what prompt you like.

However, unlike configuration features, your settings for system variables are not preserved when you switch the computer off or reset it. When you do this, the computer always goes back to the default values for the standard set of system variables, but if you have a Desktop boot file loaded, your favourite settings will be kept. You can see these default values by typing *Show just after switching on your computer.

In addition to RISC OS system variables, applications commonly use variables of their own, to control their default behaviour. For example, Edit uses variables to store your choices of display font, background colour and so on. Where there are such variables, they are listed in the chapter Configuring applications. Some suggestions for using them are also included later in this chapter.

Setting variables in a Boot file

If the default values are not the ones you want, you can change them using the *Set command. The computer does not remember system variables between sessions, so if you want different default values you must change the variable each time you use your computer. Rather than typing them each time by hand, you can include the *Set commands in a boot file (a file that is run each time you use the computer).

However, although you could create such a boot file 'by hand', typing it in Edit, a much easier way is to use the Task manager's Desktop boot facility, described in the chapter Customising the desktop start-up procedure. You will then not need to understand anything about system variables as such, since you can simply set up the desktop the way you want it and make a Desktop boot file. Creating your own boot file by editing one created by the Task manager is the easiest way to start.

Referring to variables

Each variable is accessed by its name, which can contain any character which is neither a space nor a control character. As with filenames, the case of characters is remembered, but is ignored when the names are looked up.

What are variables for?

RISC OS uses the values of variables to make the desktop work. When you double-click on a file (not an application), RISC OS looks up the alias for RUNning that file type in the variable list. If it finds a match, the command stored in the variable (for example RMLoad %*0) is executed, substituting the name of the file in place of the marker %*0; otherwise an error box is displayed.

In general, files which are displayed as white squares (they have no file type icon) will give this error if you try to use them in this way.

Application variables

There are many different system variables provided and used by RISC OS, as well as some which may be added by applications. You can see them all by typing *Show (use Shift to display each successive screenful).

The following section gives standard names used for some of the variables that are connected to a particular application.


An App$Dir variable gives the full pathname of the directory that holds the application App. This is typically set in the application's !Run file by the line:

  Set App$Dir <Obey$Dir>


An App$Path variable gives the full pathname of the directory that holds the application App. An App$Path variable differs from an App$Dir variable in two important respects:

It's common to use an App$Dir variable rather than an App$Path variable, but there may be times when you need the latter.

An App$Path variable might, for example, be set in the application's !Run file by the line:

  Set App$Path <Obey$Dir>.,%.App

if the application held further resources in the subdirectory App of the library.


An App$Options variable holds the start-up options of the application App

This variable is typically used to save the state of an application to a Desktop boot file, upon receipt of a desktop save message. A typical line output to the boot file might be;

  Set App$Options F54 M+ P4 S-

An application should only save those options that differ from the default, so there will be no line at all if the application is in its default state.


An App$PrintFile variable holds the name of the file or system device to which the application App prints. Typically this will be printer:, and would be set in your application's !Run file as follows;

  Set App$PrintFile printer:

Changing and adding commands


An Alias$Command variable is used to define a new command named Command. For example;

  Set Alias$Mode echo |<22>|<%0>

By using the name of an existing command, you can change how it works.

Using file types


A File$Type_XXX variable holds the textual name for a file having the hexadecimal file type XXX. It is typically set in the !Boot file of an application that provides and edits that file type. For example:

  Set File$Type_XXX <TypeName>

The reason the !Boot file is used rather than the !Run file is so that the file type can be converted to text from the moment its 'parent' application is first seen, rather than only from when it is run.

Alias$@LoadType_XXX, Alias$@PrintType_XXX and Alias$@RunType_XXX

These variables set the commands used respectively to load, print and run a file of hexadecimal type XXX They are typically set in the !Boot file of an application that provides and edits that file type. For example;

  Set Alias$@PrintType_XXX /<Obey$Dir> -Print
  Set Alias$@RunType_>XXX /<Obey$Dir>

Note: The above lines both have a trailing space (invisible in print!).

The reason the !Boot file is used rather than the !Run file is so that files of the given type can be loaded, printed and run from the moment their 'parent' application is first seen, rather than only from when it is run.

Setting the command line prompt


The CLI$Prompt variable sets the command line interpreter prompt. By default this is '*'. One common way to change this is so that the system time is displayed as a prompt. For example;

  SetMacro CLI$Prompt <Sys$Time> *

This is set as a macro so that the system time is evaluated each time the prompt is displayed.

There's more on this in Creating your own command line prompt later.

Configuring RISC OS commands

Copy$Options, Count$Options and Wipe$Options

These variables set the behaviour of the *Copy, *Count and *Wipe commands. For a full description type *Help command at the command line.

System path variables

File$Path and Run$Path

These variables control where files are searched for during read operations or execute operations. They are both path variables, which means that - in common with other path variables - they consist of a comma-separated list of full pathnames, each of which has a trailing '.'.

If you wish to add a pathname to one of these variables, you must ensure that you append it once, and once only. For example, to add the 'bin' subdirectory of an application to Run$Path, you could use the following lines in the application's !Boot file:

   If "<App$Path>" = "" then Set Run$Path <Run$Path>,<Obey$Dir>.bin.
   Set App$Path <Obey$Dir>.

Obey files


The Obey$Dir variable is set to the directory from which an Obey file is being run, and may be used by commands within that Obey file.

Time and date

Sys$Time, Sys$Date and Sys$Year

These variables are code variables that are evaluated at the time of their use to give, respectively, the current system time, date and year.


The Sys$DateFormat variable sets the format in which the date is presented by some commands.

!System and !Scrap

System$Dir and System$Path

These variables give the full pathname of the System application. They have the same value, except that System$Path has a trailing '.', whereas System$Dir does not. You must not change these values.

(There are two versions of this pathname for compatibility with some old applications). !System and !Scrap are contained in the !Boot application.


The Wimp$Scrap variable gives the full pathname of the Wimp scrap file used by the file transfer protocol. You must not use this variable for any other purpose, nor change its value.


The Wimp$ScrapDir variable gives the full pathname of a scrap directory within the Scrap application, which you may use to store temporary files. You must not use this variable for any other purpose, nor change its value.

The desktop


The Wimp$State variable shows the current state of the Wimp. If the desktop is running, it has the value 'desktop'; otherwise it has the value 'commands'.

Command and application options and other variables

Some commands, such as *Copy and *Wipe, can operate in a variety of ways. For example, you can effectively turn *Copy into a Move command by setting the D(elete) option, which deletes the source file after copying it to another directory or filing system. You would do this by typing

  *Set Copy$Options <Copy$Options> D

at the command line prompt. These options are described in the entries for each command in the file StarComms in the Tutorials directory.

Several applications, such as Edit, Draw, Alarm and Paint, also use system variables to record, for example, whether you want the Paint colours window to appear automatically when you open a sprite window, or whether you want the toolbox to be displayed by default in Draw. Such variables use the format App$Options, where App is the name of the application in question. These variables will only be listed in the computer's response to the *Show command if you have changed them from their default values.

In addition to 'options', applications may use other variables for a variety of purposes. For example, Acorn Desktop Publisher needs to know where its 'Work' directory is. It will find this out when the Work directory has been displayed on the screen, and it assigns the directory's pathname to the variable dtp$WorkDir. To avoid having to carry out this action each time you use the application, you can put a *Set command identifying the directory in your boot file, for example;

  *Set dtp$WorkDir <Obey$Dir>.WorkDir

Creating your own command line prompt

You can use a system variable to change the operating system prompt - normally * - by setting the variable CLI$Prompt to (for example) the character #.

  *Set CLI$Prompt #

You can also set one variable to the value of another:

  *Set CLI$Prompt <Sys$Time>

This sets the prompt to the system time, but only does so once, when the command is given. However, it would clearly be more useful if the prompt always showed the current time. To do this, change CLI$Prompt from a variable into a macro. A macro is similar to a variable, but is evaluated every time it is used, instead of just once when it is set. Therefore, type the following;

  *SetMacro CLI$Prompt <Sys$Time> *

Each time Return is pressed at the command line prompt a new prompt is given (unless you have not typed anything since the last Return; you will then be returned to the desktop); the current time is worked out and displayed, followed by a space character and an asterisk:

  12:59:06 *
  12:59:07 *
  12:59:08 *

Other uses for system variables

The names of commands may be changed using the *Set command with variables whose name starts Alias$... This allows you to add new commands, to change the meaning of existing commands, to combine commands together, and to add your own parameters to a command.

Programmers can use system variables to pass values between programs. One program can create and write to a variable which another program can then read. Such variables should have names starting App$, where App is your program; this avoids problems caused by different programs using the same system variable names.

Command scripts

Command scripts are files of commands that you would normally type in at the command line prompt. There are two main uses for such files;

You may find using an Alias$... variable to be better for the second case. The main advantage of using variables rather than command files is that they are held in memory and so are quicker in execution; however, they are only really suitable for short commands. If you use variables you will probably still want to use a command file to set them up when you switch on.

Command and Obey file types

There are two types of file you can use for command scripts: Command files, and Obey files. The differences between these two file types are:

It is recommended that you don't use *Copy and related filer commands in TaskObey files - use Filer_Action instead.

Creating a command script

A command script can be created using any text or word processor. If you created the file using Edit, you should set the file's type by pressing Menu over the Edit icon on the icon bar and choosing the desired file type, such as Command or Obey.

When you save the file you should consider in which directory you will save it. By default, files are looked for first in the current directory, then in the library. Therefore, if you want to avoid having to type the full pathname of the file every time you run it you should save it in one of the following;

Running the script

Provided that you have set the file type to Command or Obey, the file can then be run in the same ways as any other file, by

The same restrictions apply as with any other file. If the file is not in either your current directory or the library, it will not be found if you just give the filename; you must give its full pathname. This assumes you have not changed the value of the system variable Run$Path.

Making a script run automatically

You can make scripts run automatically

You'll find information on how to do this in Customising the desktop start-up procedure.

Using parameters

An Obey file - but not a Command file - can have parameters passed to it, which can then be used by the command script. The first parameter is referred to as %0, the second as %1, and so on. You can refer to all the parameters after a particular one by putting a * after the %, so %*1 would refer to all the parameters from the second one onwards.

These parameters are substituted before the line is passed to the command line interpreter. Thus if an Obey file called Display contained;

  FileInfo %0 Type %0

then the command *Display MyFile would do this;

  FileInfo MyFile
  Type MyFile

Sometimes you do not want parameter substitution. For example, suppose you wish to include a *Set Alias$ command in your file, such as:

  Set Alias$Mode echo |<22>|<%0> <Command>

The effect of this is to create a new command 'Mode'. If you include the *Set Alias command in an Obey file, when you run the file the %0 will be replaced by the first parameter passed to the file. To prevent the substitution you need to change the % to %%;

  Set Alias$Mode echo |<22>|<%%0> <Command>

Now when the file is run, the '%%0' is changed to '%0'. No other substitution occurs at this stage, and the desired command is issued.


These example files illustrate some of the differences between Command and Obey files:

Example 1

  FOR J= 1 TO 10
  PRINT "Hello"

If this is a command file, it will enter the BASIC interpreter, and input the file shown. The command script will end with the BASIC interpreter waiting for another line of input. You can then press Esc to get a prompt, type RUN to run the program, and then type QUIT to leave BASIC. This script shows how a command file is passed to the input, and can change what is accepting its input (in this case to the BASIC interpreter).

On the other hand, if this is an Obey file it will be passed to the command line interpreter, and an attempt will be made to run these commands:

  *FOR J= 1 TO 10
  *PRINT "Hello"

Only the first command is valid, as an Obey file all this does is to leave you in the BASIC interpreter. Type QUIT to leave BASIC; you will then get an error message saying File 'AUTO' not found, generated by the second line in the file.

Example 2

The next example illustrates how control characters are handled;

  echo <7>
  echo |<7>

The control characters are represented in GSTrans format (see Using GS formats in scripts). These are not interpreted until the echo command is run, and are only interpreted then because echo expects GSTrans format.

The first line sends an ASCII 7 to the VDU drivers, sounding a beep. In the second line, the | preceding the < changes it from the start of a GSTrans sequence to just representing the character <, so the overall effect is;

  echo <7> - send ASCII 7 to VDU drivers (beeps)
  echo |<7> - send <7> to the screen

Example 3

The last examples are a Command file;

  *Set Alias$more %echo |<14>|m %type -tabexpand %*0|m %echo |<15>

and an Obey file that has the same effect;

  Set Alias$more %echo |<14>|m %type -tabexpand %%*0|m %echo |<15>

The only differences between the two examples are that the Command file has a preceding * added, to ensure that the command is passed to the command line interpreter, and that the Obey file has the %*0 changed to %%*0 to delay the substitution of parameters.

The file creates a new command more by setting the variable Alias$more.

The command turns scroll mode on, types a file to the screen expanding tabs as it does so, and then turns scroll mode off.

Using GS formats in scripts

The GSTrans and GSRead formats are used by a number of commands that need to be able to handle control characters, and characters whose top bit is set. They enable you to use these characters, which would otherwise cause unpredictable output from your monitor or printer, and which would be difficult to enter directly from the keyboard. The two formats are identical.

The GSRead or GSTrans format is used by some commands to read characters that you type in. The characters are interpreted using the following conventions:

A full list of ASCII codes and how to obtain them is given below. Of course, any ASCII code may be obtained by enclosing it in angle brackets as described above, and this may be easier to remember than the symbol encoding.

ASCII code: Symbols used:

You must use |< to prevent the < from being interpreted as the start of a number or variable name enclosed in angled brackets.

To include leading spaces in a definition, the string must be in double quotation marks, ", which are not included in the definition. To include a literal " character in the string, use |" or "".

RISC OS 3.7 User Guide - 20 JAN 1997

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015