Introduction

Welcome to the Shell, the command-line interface for the Emulator.ca Systems BBS network.

Walk into any corporate computing centre or university computer lab in 1985, and you will find the same thing: programmers and system administrators working at UNIX terminals, navigating directories with cd, listing files with ls, and building complex operations from simple commands. These skills command salaries of $40,000 or more. The UNIX operating system runs on machines costing $15,000 to $100,000 - machines guarded by locked doors and system administrators who do not suffer novices gladly.

Until now.

The Shell brings UNIX-style command-line computing to your home computer through the Emulator.ca modem network. It is a working hierarchical filesystem inside your browser, with browser-local storage that persists between sessions. Create directories, write files, use wildcards and output redirection. The command names and habits you practice here echo the tools used by professionals at Bell Labs, Berkeley, and every major software company in the nation.

We have designed the Shell to follow familiar UNIX conventions where they fit a browser-local BBS service. It teaches transferable command-line habits, not full UNIX compatibility. If you already know UNIX, you will feel immediately at home. And unlike that temperamental VAX at the university computer centre, this shell is available whenever you want it - no waiting for a free terminal, no fighting for disk quota, no sysadmin asking why you are still logged in at 2 AM.

Your files are automatically preserved between sessions in this browser. Create a directory structure, write your notes and programs, and they will be waiting for you next time you dial in from the same browser profile. The Shell is your own persistent workspace on the Emulator.ca Systems network.

The file tree is simulated and browser-local. Commands such as rm, mv, and rmdir do not read, write, delete, or list files on your host computer or on the Emulator.ca server.

System Capabilities:

Complete simulated hierarchical filesystem
File and directory creation, deletion, copying, and moving
Output redirection with > and >> operators
Wildcard pattern matching with * and ?
Command history navigation with Up/Down arrow keys
Persistent browser-local storage — files are retained between sessions
Full path resolution with ., .., and ~ support
EC-SER modem flow control for terminal operation

Unlike traditional BBS systems, files and directories are automatically saved in browser-local storage and will be available on subsequent connections from the same browser profile. Users may create their own directory structure and store work between sessions. This storage is isolated from host and server files.

Quick Start

To begin using the Shell immediately:

Step 1: Dial the service

ATDT555-0760

Step 2: Once connected, try these commands:

ls              (list your files)
pwd             (show current directory)
mkdir projects  (create a new directory)
cd projects     (enter the directory)
echo "Hello" > test.txt   (create a file)
cat test.txt    (display the file)

Step 3: Explore further with help to see all available commands.

You are now ready to manage files, build directory structures, and work productively within the Shell environment.

GETTING STARTED

To access the Shell, configure the modem and dial:

ATDT555-0760

Upon successful connection, you will see the shell banner and command prompt:

ATDT555-0760
CONNECT 1200

╔═══════════════════════════════════════╗
║   BBS UNIX Shell System v1.0     ║
╚═══════════════════════════════════════╝

Welcome user! Type help for commands.
Use Up/Down arrows for command history.
Files are simulated and browser-local; host/server files are untouched.

user@bbs:/home/user$ _

The Command Prompt

The shell prompt displays your current context:

user@bbs:/home/user$

Component	Description
`user`	Your username
`bbs`	The hostname of this BBS system
`/home/user`	Your current working directory
`$`	Normal user prompt (ready for input)

The browser-local storage notice in the connection banner is literal: file commands operate only inside the simulated Shell filesystem, never on host or server files.

Command History

Use the arrow keys to navigate through your command history:

Up Arrow — Recall previous command
Down Arrow — Move forward in history
Ctrl+C — Cancel current input and get fresh prompt

The shell retains up to 50 commands in session history. Use the arrow keys to recall or modify previous commands.

FILESYSTEM STRUCTURE

The hierarchical filesystem is one of UNIX's great innovations. Instead of a flat list of files (as in CP/M or early DOS), files are organised into directories that can contain other directories, creating a tree structure. This organization scales - whether you have 10 files or 10,000, a good directory structure keeps everything findable.

The Shell provides a hierarchical filesystem modeled after UNIX System V. Upon first connection, the following directory structure is initialized:

/ (root)
├── bin/          System binaries (read-only)
├── etc/          System configuration files
│   ├── hostname  Contains system hostname
│   └── motd      Message of the day
├── home/
│   └── user/     Your home directory (~)
│       ├── README.txt
│       ├── welcome.txt
│       └── notes/
│           └── ideas.txt
├── tmp/          Temporary files
└── var/
    └── log/
        └── system.log

Directory Descriptions

Directory	Purpose
`/`	Root directory — top of the filesystem hierarchy
`/home/user`	User home directory. This is the initial working directory and where `~` resolves.
`/bin`	System binary directory (reserved for system use)
`/tmp`	Temporary storage — create scratch files here
`/etc`	System configuration files — see `motd` and `hostname`
`/var`	Variable data files — contains logs and runtime data
`/var/log`	System log files

File Attributes

Each file and directory has associated metadata:

Permissions — UNIX-style permission string (e.g., -rw-r--r--)
Size — File size in bytes
Modified — Last modification timestamp
Created — Creation timestamp

user@bbs:/home/user$ ls -l
-rw-r--r--  1 user user  285B Jan 22 14:30 README.txt
-rw-r--r--  1 user user   38B Jan 22 14:30 welcome.txt
drwxr-xr-x  1 user user    0B Jan 22 14:30 notes

NAVIGATION COMMANDS

pwd — Print Working Directory

Display the absolute path of your current directory.

SYNOPSIS: pwd

user@bbs:/home/user/notes$ pwd
/home/user/notes

cd — Change Directory

Change the current working directory.

SYNOPSIS: cd [directory]

Form	Action
`cd`	Change to home directory (~)
`cd ~`	Change to home directory
`cd /`	Change to root directory
`cd ..`	Change to parent directory
`cd path`	Change to specified path (relative or absolute)

user@bbs:/home/user$ cd notes
user@bbs:/home/user/notes$ cd ..
user@bbs:/home/user$ cd /var/log
user@bbs:/var/log$ cd ~/notes
user@bbs:/home/user/notes$ cd
user@bbs:/home/user$

ls — List Directory Contents

List files and directories.

SYNOPSIS: ls [-l] [-a] [path...]

Option	Description
`-l`	Long format — show permissions, size, and modification date
`-a`	All files — include hidden files (starting with `.`)
`-la`	Combine long format with all files

user@bbs:/home/user$ ls
README.txt  welcome.txt  notes

user@bbs:/home/user$ ls -l
-rw-r--r--  1 user user  285B Jan 22 14:30 README.txt
-rw-r--r--  1 user user   38B Jan 22 14:30 welcome.txt
drwxr-xr-x  1 user user    0B Jan 22 14:30 notes

user@bbs:/home/user$ ls /etc
hostname  motd

FILE OPERATIONS

cat — Concatenate and Display Files

Display the contents of one or more files.

SYNOPSIS: cat file [file...]

user@bbs:/home/user$ cat welcome.txt
Thank you for connecting to our BBS!

user@bbs:/home/user$ cat welcome.txt notes/ideas.txt
Thank you for connecting to our BBS!
Project ideas:
- Build a BBS
- Learn UNIX commands

touch — Create File or Update Timestamp

Create an empty file or update an existing file's modification time.

SYNOPSIS: touch file [file...]

user@bbs:/home/user$ touch newfile.txt
user@bbs:/home/user$ touch file1.txt file2.txt file3.txt
user@bbs:/home/user$ ls
README.txt  welcome.txt  notes  newfile.txt  file1.txt  file2.txt  file3.txt

rm — Remove Files

Delete one or more files. Cannot remove directories — use rmdir for that.

SYNOPSIS: rm file [file...]

There is no undelete facility. Deleted files cannot be recovered. Verify file selection before executing rm.

user@bbs:/home/user$ rm newfile.txt
user@bbs:/home/user$ rm file1.txt file2.txt file3.txt

cp — Copy Files

Copy a file to a new location.

SYNOPSIS: cp source destination

If the destination is a directory, the file is copied into that directory with its original name.

user@bbs:/home/user$ cp welcome.txt backup.txt
user@bbs:/home/user$ cp README.txt notes/
user@bbs:/home/user$ ls notes
ideas.txt  README.txt

mv — Move or Rename Files

Move a file to a new location or rename it.

SYNOPSIS: mv source destination

user@bbs:/home/user$ mv backup.txt backup-old.txt

user@bbs:/home/user$ mv backup-old.txt /tmp/

mkdir — Make Directory

Create one or more new directories.

SYNOPSIS: mkdir directory [directory...]

user@bbs:/home/user$ mkdir projects
user@bbs:/home/user$ mkdir docs archives
user@bbs:/home/user$ ls
README.txt  welcome.txt  notes  projects  docs  archives

rmdir — Remove Empty Directory

Remove an empty directory. The directory must be empty — use rm to delete files first.

SYNOPSIS: rmdir directory [directory...]

user@bbs:/home/user$ rmdir archives
user@bbs:/home/user$ rmdir notes
rmdir: failed to remove 'notes': Directory not empty

TEXT OUTPUT AND REDIRECTION

One of UNIX's most powerful ideas is that commands do not care where their output goes. By default, output appears on your terminal. But with redirection operators, you can send that output to a file instead - creating logs, building documents, or capturing results for later analysis.

This simple mechanism enables sophisticated workflows. You can build files incrementally, combine outputs from multiple commands, and create automated processes. Professional programmers use these techniques daily.

echo — Display Text

Display a line of text. Often used with redirection to write to files.

SYNOPSIS: echo [text...]

user@bbs:/home/user$ echo Hello, BBS World!
Hello, BBS World!

Output Redirection

The shell supports output redirection to write command output to files:

Operator	Description
`>`	Redirect output to file (overwrite if exists)
`>>`	Redirect output to file (append to existing content)

user@bbs:/home/user$ echo "Hello World" > hello.txt
user@bbs:/home/user$ cat hello.txt
Hello World

user@bbs:/home/user$ echo "Line 1" > mylog.txt
user@bbs:/home/user$ echo "Line 2" >> mylog.txt
user@bbs:/home/user$ echo "Line 3" >> mylog.txt
user@bbs:/home/user$ cat mylog.txt
Line 1
Line 2
Line 3

user@bbs:/home/user$ date > timestamp.txt
user@bbs:/home/user$ pwd >> paths.log
user@bbs:/home/user$ uname -a > system-info.txt

Use > to create new files or overwrite existing ones. Use >> to append content to existing files, which is useful for log files.

WILDCARDS (GLOBBING)

Here is where command-line efficiency truly shines. Instead of typing individual filenames, wildcards allow you to specify multiple files with a single pattern. Need to delete all your backup files? Remove all .bak files with one command. Want to see only your text files? ls *.txt shows exactly those.

The shell expands wildcard patterns before executing commands - it builds the list of matching files and passes them to the command. This happens automatically and invisibly.

Wildcard	Matches
`*`	Any sequence of characters (including empty)
`?`	Any single character

user@bbs:/home/user$ ls *.txt
README.txt  welcome.txt  hello.txt

user@bbs:/home/user$ touch file1.bak file2.bak config.bak
user@bbs:/home/user$ ls *.bak
file1.bak  file2.bak  config.bak
user@bbs:/home/user$ rm *.bak
user@bbs:/home/user$ ls *.bak
ls: cannot access '*.bak': No such file or directory

user@bbs:/home/user$ touch log1.txt log2.txt log3.txt
user@bbs:/home/user$ ls log?.txt
log1.txt  log2.txt  log3.txt

user@bbs:/home/user$ cat *.txt > all-content.txt

If no files match a wildcard pattern, the literal pattern is kept. For example, if there are no .bak files, ls *.bak will look for a file literally named *.bak.

PATH RESOLUTION

Paths can be specified in multiple ways. Understanding path resolution is key to efficient shell navigation.

Absolute Paths

Absolute paths start with / and specify the complete location from the root:

/home/user/notes/ideas.txt
/etc/motd
/var/log/system.log

Relative Paths

Relative paths are interpreted from your current directory:

notes/ideas.txt        # File in subdirectory
myfile.txt             # File in current directory

Special Path Components

Symbol	Meaning
`.`	Current directory
`..`	Parent directory
`~`	Home directory (`/home/user`)
`~/path`	Path relative to home directory

user@bbs:/home/user$ cd notes
user@bbs:/home/user/notes$ cat ../welcome.txt    # Parent directory
Thank you for connecting to our BBS!

user@bbs:/home/user/notes$ cat ~/README.txt      # Home directory
Welcome to the Shell!
...

user@bbs:/home/user/notes$ cat ./ideas.txt       # Current directory
Project ideas:
- Build a BBS
- Learn UNIX commands

user@bbs:/home/user/notes$ cd ../..              # Go up two levels
user@bbs:/home$ cd ~                             # Return home
user@bbs:/home/user$

Multiple .. components may be chained to traverse several levels: cd ../../.. ascends three directories.

SYSTEM COMMANDS

clear / cls — Clear Screen

Clear the terminal screen.

SYNOPSIS: clear
ALIAS: cls

whoami — Display Username

Print the current username.

SYNOPSIS: whoami

user@bbs:/home/user$ whoami
user

date — Display Date and Time

Show the current system date and time.

SYNOPSIS: date

user@bbs:/home/user$ date
Wed Jan 22 2026 14:30:45 GMT-0500 (Eastern Standard Time)

uname — System Information

Print system information.

SYNOPSIS: uname [-a]

Option	Output
(none)	Operating system name: `BBS-UNIX`
`-a`	All system information

user@bbs:/home/user$ uname
BBS-UNIX

user@bbs:/home/user$ uname -a
BBS-UNIX bbs 1.0.0 #1 Wed Jan 22 2026 x86_64 GNU/BBS

help — Display Help

Show available commands and their usage.

SYNOPSIS: help

exit / quit / logout — Disconnect

End the shell session and disconnect from the BBS.

SYNOPSIS: exit
ALIASES: quit, logout

COMMAND REFERENCE TABLE

Command	Synopsis	Description
pwd	pwd	Print current working directory
cd	cd [dir]	Change directory (default: home)
ls	ls [-la] [path]	List directory contents
cat	cat file...	Display file contents
touch	touch file...	Create empty file / update timestamp
mkdir	mkdir dir...	Create directories
rm	rm file...	Remove files
rmdir	rmdir dir...	Remove empty directories
cp	cp src dest	Copy file
mv	mv src dest	Move / rename file or directory
echo	echo text	Display text
clear	clear	Clear screen
whoami	whoami	Print username
date	date	Show date/time
uname	uname [-a]	System information
help	help	Show command help
exit	exit	Disconnect from BBS

TIPS AND TRICKS

Efficient Navigation

Use cd without arguments to return to home directory
Combine .. components to traverse multiple levels: cd ../../..

File Management

Use ls -l to view file sizes before copying
Create a backup/ directory to store copies of important files
Use wildcards to operate on multiple files simultaneously

Building Content

Use echo "text" > file to create files with initial content
Use echo "more" >> file to append content incrementally
Combine cat with wildcards to merge multiple files

Quoting

Use double quotes to include spaces in your text:

echo "Hello, World!" > greeting.txt
echo 'Single quotes work too' >> messages.txt

Command History Shortcuts

Press Up Arrow repeatedly to find older commands
Press Down Arrow to return to more recent commands
Press Ctrl+C to cancel and start fresh

EXAMPLE SESSION

The following transcript demonstrates a typical shell session:

ATDT555-0760
CONNECT 1200

╔═══════════════════════════════════════╗
║   Shell System v1.0                ║
╚═══════════════════════════════════════╝

Welcome user! Type help for commands.
Use Up/Down arrows for command history.

user@bbs:/home/user$ ls
README.txt  welcome.txt  notes

user@bbs:/home/user$ cat README.txt
Welcome to the Shell!

This is a functional shell with file operations.
Type "help" for a list of commands.

user@bbs:/home/user$ mkdir projects
user@bbs:/home/user$ cd projects
user@bbs:/home/user/projects$ echo "My BBS Project" > project.txt
user@bbs:/home/user/projects$ echo "Started: January 2026" >> project.txt
user@bbs:/home/user/projects$ echo "Status: In Progress" >> project.txt
user@bbs:/home/user/projects$ cat project.txt
My BBS Project
Started: January 2026
Status: In Progress

user@bbs:/home/user/projects$ ls -l
-rw-r--r--  1 user user   52B Jan 22 14:35 project.txt

user@bbs:/home/user/projects$ cp project.txt backup.txt
user@bbs:/home/user/projects$ ls
project.txt  backup.txt

user@bbs:/home/user/projects$ cd ..
user@bbs:/home/user$ ls -l projects/
-rw-r--r--  1 user user   52B Jan 22 14:35 project.txt
-rw-r--r--  1 user user   52B Jan 22 14:36 backup.txt

user@bbs:/home/user$ pwd
/home/user

user@bbs:/home/user$ date > ~/.login_time
user@bbs:/home/user$ whoami
user

user@bbs:/home/user$ uname -a
BBS-UNIX bbs 1.0.0 #1 Wed Jan 22 2026 x86_64 GNU/BBS

user@bbs:/home/user$ exit
Goodbye!

NO CARRIER

ERROR MESSAGES

Common error messages and their meanings:

Error	Cause
`command not found: xxx`	Unknown command — check spelling or use `help`
`No such file or directory`	Path does not exist — verify with `ls`
`Not a directory`	Tried to `cd` into a file, or use file as path component
`Is a directory`	Tried to `cat` or `rm` a directory
`File exists`	Tried to `mkdir` when name already exists
`Directory not empty`	Tried to `rmdir` a directory with files — remove files first
`missing file operand`	Command requires filename argument
`missing operand`	Command requires argument(s)

Appendix A: Quick Reference Card

╔═══════════════════════════════════════════════════════════════════╗
║                   SHELL QUICK REFERENCE                        ║
╠═══════════════════════════════════════════════════════════════════╣
║  NAVIGATION                    FILE OPERATIONS                    ║
║  ──────────                    ───────────────                    ║
║  pwd      Show current dir     cat FILE    Display file           ║
║  cd DIR   Change directory     touch FILE  Create empty file      ║
║  cd       Go to home (~)       rm FILE     Delete file            ║
║  cd ..    Go up one level      cp SRC DST  Copy file              ║
║  ls       List files           mv SRC DST  Move/rename file       ║
║  ls -l    Long listing         mkdir DIR   Create directory       ║
║  ls -a    Show hidden files    rmdir DIR   Remove empty dir       ║
║                                                                   ║
║  REDIRECTION                   SPECIAL PATHS                      ║
║  ───────────                   ─────────────                      ║
║  cmd > file   Overwrite        ~     Home directory               ║
║  cmd >> file  Append           .     Current directory            ║
║                                ..    Parent directory             ║
║  WILDCARDS                                                        ║
║  ─────────                     SYSTEM COMMANDS                    ║
║  *   Match any chars           ───────────────                    ║
║  ?   Match single char         whoami   Show username             ║
║                                date     Show date/time            ║
║  SESSION                       uname    System info               ║
║  ───────                       clear    Clear screen              ║
║  Up/Down  Command history      help     Show all commands         ║
║  Ctrl+C   Cancel input         exit     Disconnect                ║
╚═══════════════════════════════════════════════════════════════════╝

Appendix B: Troubleshooting

Common Problems and Solutions

Problem: Command not found

Cause: The command was mistyped or does not exist.

Solution: Check your spelling and use help to see the list of available commands. Shell commands are case-sensitive and must be entered in lowercase.

Problem: No such file or directory

Cause: The specified path does not exist.

Solution: Use ls to verify the file or directory exists. Check for typos in the path. Remember that paths are case-sensitive.

Problem: Directory not empty

Cause: Attempted to remove a directory that contains files.

Solution: First remove all files within the directory using rm, then use rmdir to remove the empty directory.

Problem: Permission denied

Cause: Attempted to modify a system directory or read-only file.

Solution: Some directories (such as /bin) are reserved for system use. Work within your home directory (/home/user) or /tmp.

Problem: Connection dropped unexpectedly

Cause: Modem carrier loss or line noise.

Solution: Reconnect and dial again. Your files are automatically saved—no work is lost.

Appendix C: Glossary

Absolute Path — A file path that begins with / and specifies the complete location from the root directory. Example: /home/user/notes/ideas.txt

Current Directory — The directory you are presently working in, shown in the command prompt and returned by pwd.

Globbing — The process of expanding wildcard patterns (* and ?) to match multiple files.

Home Directory — Your personal directory, typically /home/user. The ~ symbol is a shortcut to this location.

Parent Directory — The directory one level above the current directory, referenced as .. in paths.

Redirection — Sending command output to a file instead of the screen, using > (overwrite) or >> (append).

Relative Path — A file path interpreted from the current directory, not beginning with /. Example: notes/ideas.txt

Root Directory — The top-level directory of the filesystem, represented by /.

Working Directory — See Current Directory.

Appendix D: A Typical Working Session

Here is how an experienced user might approach a real task - organizing project files and creating a simple log:

user@bbs:/home/user$ mkdir -p projects/bbs-game
user@bbs:/home/user$ cd projects/bbs-game
user@bbs:/home/user/projects/bbs-game$ echo "BBS Adventure Game" > README.txt
user@bbs:/home/user/projects/bbs-game$ echo "Started: January 1986" >> README.txt
user@bbs:/home/user/projects/bbs-game$ echo "Goal: Create text adventure" >> README.txt
user@bbs:/home/user/projects/bbs-game$ mkdir src docs
user@bbs:/home/user/projects/bbs-game$ ls -l
drwxr-xr-x  1 user user    0B Jan 22 15:30 src
drwxr-xr-x  1 user user    0B Jan 22 15:30 docs
-rw-r--r--  1 user user   67B Jan 22 15:30 README.txt
user@bbs:/home/user/projects/bbs-game$ cat README.txt
BBS Adventure Game
Started: January 1986
Goal: Create text adventure

Notice the workflow: create a project directory, change into it, establish documentation, create subdirectories for organization, verify the results. This pattern - plan, execute, verify - serves well in any command-line environment.

What To Explore Next

You now have the skills to navigate and manipulate a UNIX-style filesystem. These commands will serve you well whether you pursue system administration, software development, or simply want to organise your work effectively.

Deepen Your Shell Skills

Practice combining commands: ls *.txt shows only text files, cat *.log >> archive.txt combines log files
Create a personal organization system using directories for different projects
Use the shell to prepare input files for other BBS services

Related Services

The Shell integrates well with other Emulator.ca Systems services:

SLP-BASIC (555-0300) - Write programs and save them to your shell directories
System Information (555-0600) - Monitor the system you are working on
Stock Ticker (555-0755) - Financial data analysis, export reports to files

The Path Forward

The commands you have learned here - cd, ls, cat, cp, mv, rm, mkdir - are the foundation of command-line computing. Master these, and you will be comfortable on any UNIX system: the Sun workstations appearing in engineering firms, the VAXen running at universities, or the new 386 machines that will soon bring UNIX to the desktop.

The Shell is your training ground. Experiment freely - your home directory is yours to organise as you see fit. Build something. Break something (you can always mkdir it again). The best way to learn is by doing.

Shell Reference Manual - Emulator.ca Systems

Document Revision 1.0