Using the terminal

An introduction to using Bela on the command line

Though it’s small, Bela is a full Linux system. As well as using the browser-based IDE, you can manipulate the files in your Bela system using your computer’s command line. On this page, we show you the basics of interacting with Bela using the command line. Open a terminal and go through the instructions below, and try some of the techniques listed here.

(Note that in this wiki we use the convention here that commands to be typed by the user are here displayed prepended by a $, while the output of a program is displayed without the leading $.)

Execute a program

Executing a program is as simple as typing its name and hit enter. Once your terminal is open, try typing the following

$ ls

file1
file2
file3

again, according to the convention mentioned above, in this snippet you will only have to type ls followed by enter, and the program will output a list of the files contained in the current folder. So we learned the command ls, which lists the files in the current directory. Again, executing a program is as simple as typing its name followed by enter

Get help

Often times commands accept options that allow to modify their default behaviour. Most of the time, it is possible to obtain help on a command and info on the supported options by typing --help after the program name. Make sure you leave a space between the program name and the --help option.

$ ls --help
usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]

Now, the sample response above was not very informative. The response above was from a Mac OSX machine, it may be different (e.g.: more informative) on your machine. A way of obtaining more exhaustive help on a program is to prepend the command name with man.

$ man ls

On systems that support man, this will bring up a detailed help file which you can browse with the up and down arrow keys and you can quit by pressing q.

Pass options to a program

As mentioned, a program may allow (or require) additional options beside the command name. We have already seen two examples above of how to pass options to a program:

$ ls --help

passed the option --help to the program ls and

$ man ls

passed the option ls to the program man.

As a general rule, the program name is going to be the first word of the line (apart for some special cases) and anything else that is separated from it by spaces is considered to be an option passed to the program. If you want to pass multiple options, you will again have to leave a space between them. For instance the following command

$ ls -l -h

will list the files in the folder with the -l option (which means long format) and the -h option (which means human-readable sizes).

Browsing the filesystem

You will often find that you have to move to a different folder than the one you are in before you are able to execute a particular program. To know the folder you are currently in, use pwd (print working directory):

$ pwd
/Users/yourname

To move to a different directory, use cd (change directory):

$ cd Desktop

you will have noticed that this command did not produce any output. Nothing to be worried about. When cd succeeds, it produces no output. Now try

$ cd Bela-master

if you get something like

bash: cd: Bela-master: No such file or directory

then it means that you probably did not download this [[archive|https://github.com/BelaPlatform/Bela/archive/master.zip]] and unzipped it on your desktop. Do that before proceeding and make sure the cd Bela-master command succeeds before continuing.

Prepare to use the Bela scripts

Now that you know everything (you need) about the terminal and you are in the Bela-master folder, have a look at the content of the scripts/ folder. To do so run

$ cd scripts 
$ ls
build_pd_heavy.sh
build_project.sh
connect_to_project.sh
halt_board.sh
hvresources
ide.sh
run_project.sh
set_startup.sh
setup_ssh.sh
stop_running.sh
update_board

Of the listed files, hvresources is a folder (and depending on your shell’s settings, it may be displayed in a different color), while all the others are the Bela scripts. The help for each of those can be reached adding the --help option. This will give you a description of what the program does and what options it takes. Try, e.g.:

$ ./update_board --help

note that there is only one small (but crucial) difference from all the examples above: the program name is now preceded by a “./”. This tells the shell to “look for the file in the current folder”. This is not needed for programs like ls or pwd which reside somewhere else on your disk drive.

Every time you use a Bela script, you need to prepend “./” to its name, otherwise you would get something like

$ update_board
bash: update_board: command not found