The AmigaDOS Shell¶

The Shell is AmigaDOS's command-line interpreter, built into Kickstart ROM. It implements a small language descended from Tripos, extended over the years with variable substitution, pipes, back-tick expansion, and redirection. Besides interactive use, the Shell boots the system by running the Startup-Sequence script in the S: assign, and user programs can launch a Shell to interpret scripts. This article summarizes the language from the 2024 ROM Kernel Reference Manual (Ch. 15).

Command lines¶

The Shell reads commands line by line. Each line is a command plus arguments separated by spaces or tabs. An argument may be a bare value or a keyword=value pair (no spaces around =). Commands are resolved as an alias, a script, or an executable on the path — which always includes the current directory and the C: assign (extend it with the Path command).

I/O redirection¶

Operator	Effect
`>path`	Redirect output to a file (create/overwrite)
`>>path`	Append output to a file
`<path`	Redirect input from an existing file
`<<ind`	Here-doc: read the script/console until a line starting with `ind` (V45+)
`<>path`	Redirect both stdin and stdout to a file (e.g. detach to `NIL:`)
`*>path`	Redirect error output to a file; if interactive, also sets the console process (V45+)
`*>>path`	Append error output (V45+)
`*<>`	Create an error stream merged into stdout (V45+)

Redirection operators must be separated from arguments by spaces/tabs. Placement usually doesn't matter, except for Run/Alias (redirection must follow the command directly), and for all commands if the oldredirect variable is set (which emulates the V33 BCPL CLI).

Compound commands (V45+)¶

Operators that sit between commands (space-separated):

| — pipe: left command's stdout becomes the right command's stdin. The pipe can be addressed explicitly as PIPE:. Requires the Queue-Handler.
|| — concatenate two commands' output into one stream (not the bash meaning).
&& — run the right command only if the left one's return code is below the FailAt threshold.
( ... ) — group commands into a sub-shell (separate process).

Unary operators¶

& — run the command line in the background (like Run).
+ — at end of line: append the next input line to this command's argument line (used with Run to build multi-line background scripts).
; — comment: everything after is ignored.

Quoting and escaping¶

Double quotes ("...") protect spaces, tabs, =, and operators. A quote only starts a quoted string at the start of a line or after a space/tab; a quote always terminates one. The asterisk * is the escape character:

Substituted only inside double quotes (left for the program to replace, typically via ReadArgs()):

Sequence	Meaning
`*N`	newline (0x0a)
`*E`	ESC (0x1b); use `*E[` for the 7-bit CSI equivalent
`*"`	literal double quote
`**`	literal asterisk

Substituted everywhere by the Shell itself:

Sequence	Meaning
`*$`	literal `$`
*``	literal back-tick
`[` / `]`	literal square bracket (only meaningful inside alias expansion)

So Echo "Hello*NThere" prints on two lines (Echo/ReadArgs substitutes *N), while Echo Hello*NThere prints literally — escape substitution depends on the executed program using ReadArgs()/ReadItem().

Variables and expansion¶

A variable reference starts with $ followed by alphanumerics (case-insensitive), or ${name} allowing /-separated hierarchical names. Local variables (in pr_LocalVars) take priority over global variables (files in the ENV: assign). Undefined variables are left unexpanded.

Prefix	Behavior
`$name`	expand the variable
`$?name`	substitute `1` if defined, else `0`
`$??name`	`1`/`0` for global variables only
`$!name`	binary expansion (may contain control chars); global only, must be quoted

Predefined / configuration variables¶

Set by the Shell:

process — the CLI task number (unique per Shell; useful for temp-file names).
RC — return code of the last command (compared against FailAt to abort scripts).
Result2 — the DOS error code (IoErr()) of the last failed command (printed by Why).

Read by the Shell to configure it (booleans accept on/1/yes/TRUE, case-insensitive):

VIEWER — program to display non-executable files.
echo — echo each command (script debugging).
debug — write all commands to the serial port (9600 8N1); captured to RAM:syslog if boot-menu logging is on.
oldredirect — V33-style redirection placement.
interactive — single-step trace scripts (Return/y run, Del/n skip, Esc/q stop).
simpleshell — disable TAB expansion (cooked-mode line input).
histsize — history size in lines.
histskipdups — don't store duplicate commands.

Back-tick and alias expansion¶

Back-ticks (` `command` `) run the enclosed command first and substitute its stdout (newlines become spaces) into the command line. V36 allowed one pair per line; V45 lifted the limit. The substituted text is itself re-parsed and may even contain operators — wrap in double quotes to suppress re-interpretation.

Aliases are local macros (Alias name definition). When a command name matches an alias, it is replaced by the definition; the token [] in the definition is replaced by the command's remaining arguments. An alias cannot expand itself twice on one line (recursion guard).

Command execution¶

After all expansion, the Shell locates the command: resident list first (if unquoted), then the path. If a located file is neither executable nor a script, the VIEWER variable names a program to display it (defaulting to MultiView). Argument parsing inside commands normally uses dos.library's ReadArgs()/ReadItem() (see dos.library Reference), which is what makes the Shell's quoting/*N conventions work consistently.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search