The shell and the editor

When no program runs, a computer shows its prompt and waits for a command: this is the shell. From there you copy examples, manage files and folders, open the editor to write code, and run programs. This page lists everything the shell and the editor can do. The screens below come from a Personal Computer (51 columns); on a Tube Computer the same text wraps at 40 columns.

#The prompt

Brass OS 1.0
Tier 4 - 131072 cells
Type help to get started.
>

The prompt is > at the root of the medium and shows the current folder elsewhere, like /games/snake>. A very long path is shortened from the left with ....

Type a command and press Enter. The line can be edited before that:

A line holds up to 1,024 characters. Commands and file names are case-sensitive: Help is not help. Errors show in red.

#Running a program

Type the name of a file to run it, followed by its arguments if it takes some:

> blink
> games/snake/main
> pulse left 3

The shell first looks for a command with that name, then for a file. A file named like a command (a file called help, say) can still be run with run help. If nothing matches, the shell answers No such program: <name>; if the name is a folder, it suggests 'games' is a folder: cd games.

While a program runs, the prompt is gone: what you type goes to the program (to read() or as key events). When the program ends or stops on an error, the prompt comes back.

#Tab completion

Tab completes the last word of the line as far as it can:

• the first word: a command or a file of the current folder (exa becomes examples);
• after examples: an example name (examples seq becomes examples sequencer);
• anywhere else: a path, folder by folder (cd /ga becomes cd /games/, a folder getting its slash).

When several names start the same way, Tab completes their common beginning; type a letter more and press Tab again.

#Commands

#help

help lists the commands, then the libraries this computer has (a Tube Computer has no gfx or net), then a few hints. help <library> lists the functions of a library:

> help rs
rs: get, get_output, set, sides
> help os
os: clock, day_time, id, label, memory, pull_event,
 queue_event, reboot, shutdown, start_timer, tier,
time
> help lamp
No library 'lamp'

The full documentation of each function is on this site (rs, os...) and in the editor, when the mouse rests on a name.

#examples

examples lists the built-in programs this computer can run, and says how many more a newer computer would offer. examples <name> copies one onto the medium, under its own name or under the name you give:

> examples blink
Saved as 'blink'. Read it: edit blink   Run it: bli
nk
> examples blink
'blink' already exists: 'examples blink <other name
>'
> examples blink lamp
Saved as 'lamp'. Read it: edit lamp   Run it: lamp

The copy is an ordinary file, commented in the language of the player at the keyboard: read it, change it, break it, copy it again. A program that needs a newer computer is refused with This computer has no 'net' library or This example needs a personal computer or newer. The Built-in programs pages explain each one.

#ls

ls lists the current folder (or the folder given): folders first, in light blue with a slash, then files. The last line tells the free space of the whole medium:

> ls
games/  lib/  blink  startup
60703 / 65536 bytes free
> ls games
snake/  pong
60703 / 65536 bytes free

An empty folder shows (empty). ls nowhere answers No folder 'nowhere', and ls blink answers 'blink' is a file.

#cd

cd games enters a folder, cd .. goes up one level, cd alone goes back to the root. Programs started from a folder work in that folder: their file names are relative to it (fs.cwd() tells which one it is).

> cd games
/games> cd snake
/games/snake> cd ..
/games> cd
>

#mkdir

mkdir games creates a folder; mkdir games/snake/levels creates every missing folder of the path at once. If the name is taken: 'games' already exists.

#cat

cat <file> prints a file on the screen, handy to glance at a short file or at the data a program saved. A long file scrolls past: open it with edit instead.

#edit

edit <file> opens the file in the editor. If the file does not exist yet, the editor opens empty and the file is created the first time you save. edit <folder> opens the editor with the tree of that folder on the left, and edit alone opens the current folder.

#run

run <file> [arguments] runs a program; typing the file name directly does the same. The words after the name are the arguments, given to the program in the global table arg: arg[1], arg[2]..., always as strings, and arg[0] is the path of the file. Words are separated by spaces, and quotes do not group them.

-- pulse <side> <count>: sends short redstone pulses
local side = arg[1] or "top"
local times = tonumber(arg[2]) or 1
for i = 1, times do
  rs.set(side, true)
  sleep(0.2)
  rs.set(side, false)
  sleep(0.2)
end
print("Sent " .. times .. " pulse(s) to " .. side)

> pulse left 3
Sent 3 pulse(s) to left
> pulse
Sent 1 pulse(s) to top

arg[1] or "top" gives a default value when the argument is missing, and tonumber turns the text "3" into the number 3 (or nil for anything else). #arg is the number of arguments.

#rm

rm <file> deletes a file, or an empty folder. A folder with something inside needs rm -r, which deletes it with everything it contains:

> rm games
'games' is not empty: rm -r games
> rm -r games

#cp and mv

cp <from> <to> copies a file or a whole folder; mv <from> <to> moves or renames it. When the destination is an existing folder, the file goes inside it, under the same name:

> mv blink startup
> cp startup backup/startup
> mv lamp games

The first line renames, the second copies into a folder (created if needed), the third moves lamp into the existing folder games. An existing file at the destination is replaced without warning. A folder cannot be moved inside itself.

#label

label alone shows the computer's name, label <name> sets it (32 characters at most; longer names are cut). The label shows in Engineer's Goggles, in id and to other computers through net.computers(). To remove it, type brass, then os.label(nil).

> label
No label
> label Iron furnace
> id
Computer #7 "Iron furnace"

#mem

mem measures the memory in use, in cells, out of the computer's total:

> mem
Memory: 63 / 131072 cells

The global variables of the programs that ran since the last reboot still count: a program that filled a global table leaves it behind until reboot. See Memory.

#id

id prints the computer's number (Computer #7), and its label if it has one. The number is unique in the world, and programs read it with os.id().

#clear

clear erases the screen, text and drawings, and puts the prompt back at the top.

#brass: the interactive interpreter

brass turns the prompt into a calculator that speaks Brass: type an expression and its value is printed, type a statement and it runs. It is the quickest way to try a function or check a value.

> brass
Brass 1.0 - type 'exit' to leave.
brass> 1 + 2
3
brass> 2 ^ 10
1024
brass> "iron" .. " ingot"
iron ingot
brass> string.upper("redstone")
REDSTONE
brass> x = 64
brass> x * 9
576
brass> local y = 5
brass> y
brass> for i = 1, 3 do print(i) end
1
2
3
brass> exit
>

• An expression prints its value; nil prints nothing, and a table prints as table: 0x....
• Each line is a small program of its own: a local disappears at the end of its line (above, y is nil on the next line). Globals stay, so write x = 64, not local x = 64, to keep a value for the next lines.
• Globals left by the last programs are there too: after a program stopped on an error, brass lets you look at its global variables.
• A mistake prints the error in red (brass:1: attempt to call a nil value (global 'pritn')) and you can go on.
• Tab completes global names and library members (term.set_c becomes term.set_cursor), and ↑ recalls the previous lines.
• exit goes back to the shell. So does Ctrl+T at the brass> prompt; while a line runs (an endless loop, say), the first Ctrl+T stops that line and the second leaves.

#reboot and shutdown

reboot restarts the computer like the Reboot button: the memory is wiped, the outputs are released, the banner comes back and startup runs. shutdown switches it off like the Switch off button: it stays off, blank, until someone presses Switch on in its terminal. See Power, reboot and the terminal buttons.

#Folders and paths

A medium holds files and folders, like a computer disk. Names use letters (no accents), digits, _, . and -, up to 32 characters.

Paths work in every command and in programs: fs.read() and the other fs functions understand them the same way. A program split into several files loads the others with import(), whose paths start from the folder of the importing file. See Modules.

#The startup file

A file named startup at the root of the medium runs by itself every time the computer boots: when it starts turning, after Reboot or Switch on, when its chunk loads again. Put your controller in it and it never needs you again.

> mv blink startup
> reboot

When startup ends (or stops on an error), the prompt appears. Ctrl+T stops it like any program.

#The editor

edit <file> opens a code editor in the spirit of VS Code: line numbers, colours, indentation guides, a status bar with the cursor position (Ln 12, Col 5) and the size of the file against the room left on the medium (1234 / 65000 characters). A file with unsaved changes shows ● modified next to its name.

#Writing code

• Completion: as you type a name, a list proposes the keywords, the functions and the variables of the file. After term. it lists the functions of term, after a wrapped block (light.) the methods of that block, after name: the string methods. It only offers what this computer has: no net on a Tube Computer. Tab or Enter accepts, ↑ ↓ choose (and PageUp PageDown by 8), Esc closes, a click picks. A function is written with its parentheses, the cursor inside them when it takes arguments; a library gets its dot and the list of its members opens. Ctrl+Space opens the list anywhere.
• Signature: inside a call, the editor shows the function's arguments above the cursor, the one you are typing in yellow: term.set_cursor(x, y).
• Documentation: rest the mouse on a function, a library or a method (print, term.write, math, light.set...) and a box shows what it does, its arguments (the optional ones in grey) and an example. A library this computer lacks says so. For a method of a wrapped block, the box shows every kind of block that has it, unless the file wraps it with a type (peripheral.find("inventory")).
• Indentation: Enter keeps the indentation of the line, and adds a level (two spaces) after then, do, else, repeat, function(...) or an opening bracket. When the block has no end yet, the editor writes it (or until after repeat). end, else, elseif, until and closing brackets move back to their block's level by themselves. Backspace in the indentation removes a whole level.
• Pairs: (, [, { and quotes close themselves; typing the closing character steps over it, and Backspace between an empty pair removes both. With text selected, typing a bracket or a quote wraps the selection.

#Keys

With the mouse: click to place the cursor, drag or Shift+click to select, double-click to select a word, the wheel to scroll (Shift+wheel to scroll sideways).

#Saving

Ctrl+S (or the Save button) writes the file on the medium and shows Saved. Esc (or Back) returns to the terminal; if a file has unsaved changes, the status bar warns Not saved: Esc again to leave anyway, Ctrl+S to save. A file cannot grow beyond the room left on the medium: the editor then says The medium is full: N characters at most.

#Several files: the folder tree

edit <folder>, or edit alone for the current folder, opens the editor with the tree of the folder on the left. It shows startup or main first if the folder has one.

• Click a file to open it. Several files stay open, each with its changes and its undo history; a file with unsaved changes is marked ● in the tree. Ctrl+S saves the file shown, so save each one.
• Click a folder to fold or unfold it.
• + File and + Folder create one in the folder clicked last (a blue mark shows it; click below the files for the top folder). Type the name, Enter to create, Esc to cancel. A name may contain / to create sub-folders on the way.

The multi-file project recipe puts all of this to work.

#The terminal keys

In the terminal, these keys work at any time, even while a program runs:

Every other key goes to the program: letters as char events, and Enter, Backspace, Delete, the arrows, Home, End and Tab as key events. A click on the screen sends a click event, and moving the mouse with a button held sends drag events (not on the paper of the Tube Computer). The Events page and the keys reference show how programs use them.

#See also

• Your first program, the tutorial that goes through the basics of the shell.
• The computers, what each computer has.
• fs, to handle files from a program, and os for os.reboot, os.shutdown and os.label.