ls, cd, and cat — Terminal Filesystem Navigation Commands

The Virtual Filesystem

guest-portfolio.dev ships a fully in-memory filesystem tree defined in utils/fileSystem.js. Every file has Unix-style metadata — permissions, size, and a modification date — so navigation feels identical to a real shell session.

~ (home)
├── about.md            -rw-r--r--   1024   Oct 24 10:05
├── skills.sh           -rwxr-xr-x   2048   Oct 24 10:10
├── references.log      -rw-r--r--   8192   Oct 24 10:40
├── projects/           drwxr-xr-x   4096   Oct 24 10:15
│   ├── terminal-portfolio.md
│   └── mainframe-ai.md
├── blog/               drwxr-xr-x   4096   Oct 24 10:30
│   ├── why-i-love-vim.md
│   └── leaving-the-ui-behind.md
└── case-studies/       drwxr-xr-x   4096   Oct 24 10:45
    └── migration-to-k8s

Path resolution is handled by the resolveNode helper in fileSystem.js. It walks the tree segment by segment, supports .. and ~, and returns either a resolved { node, path } object or an { error } object that the terminal renders in red.

`ls` — List Directory Contents

Syntax

ls [dir]
ls -la [dir]

Description

Lists every child node inside a directory. Each entry is rendered as a single row with four fields:

Field	Width	Notes
Permissions	10 chars (`w-24`)	e.g. `drwxr-xr-x`, `-rw-r--r--`
Size	right-aligned (`w-16`)	Bytes as stored in the filesystem tree
Date	fixed-width (`w-32`)	e.g. `Oct 24 10:15`
Name	coloured	Directories → amber bold with trailing `/`; executables → green bold; regular files → default white

ls -la is fully equivalent to ls. The -la flag is recognised and accepted, and the output format is identical — full metadata is always shown.

Examples

List the home directory:

ls

-rw-r--r--   1024   Oct 24 10:05   about.md
-rwxr-xr-x   2048   Oct 24 10:10   skills.sh
drwxr-xr-x   4096   Oct 24 10:15   projects/
drwxr-xr-x   4096   Oct 24 10:30   blog/
-rw-r--r--   8192   Oct 24 10:40   references.log
drwxr-xr-x   4096   Oct 24 10:45   case-studies/

List a subdirectory by name:

ls projects/

-rw-r--r--   512    Oct 24 10:20   terminal-portfolio.md
-rw-r--r--   856    Oct 24 10:25   mainframe-ai.md

List with the -la flag:

ls -la blog/

-rw-r--r--   2048   Oct 24 10:35   why-i-love-vim.md
-rw-r--r--   3142   Oct 24 10:38   leaving-the-ui-behind.md

Error Cases

Path does not exist:

ls documents/

cd: documents/: No such file or directory

Targeting a file instead of a directory:
When ls resolves to a file node rather than a directory, it prints just the filename rather than a listing.

`cd` — Change Directory

Syntax

cd [dir]

Description

Changes the terminal’s current working directory (cwd). The new path is reflected in the prompt immediately:

guest@portfolio.dev:~/projects$

Supported Path Forms

Form	Example	Behaviour
Relative path	`cd projects/`	Resolved relative to `cwd`
Parent traversal	`cd ..`	Moves one level up; stops at `~`
Current dir	`cd .`	No-op — stays in the same directory
Home shortcut	`cd ~`	Jumps directly to `~`
Absolute from home	`cd ~/blog`	Resolves from `~` regardless of `cwd`
No argument	`cd`	Equivalent to `cd ~`

Examples

Navigate into a subdirectory:

cd projects/

Prompt changes to guest@portfolio.dev:~/projects$. No output is printed on success. Go up one level:

cd ..

Jump home from anywhere:

cd ~

Absolute path from home:

cd ~/case-studies

Error Cases

Directory does not exist:

cd nowhere

cd: nowhere: No such file or directory

Targeting a file:

cd about.md

cd: about.md: Not a directory

`cat` — Read File Contents

Syntax

cat [file]

Description

Reads a file from the virtual filesystem and renders its contents. The terminal distinguishes three special files and falls back to the stored content string for everything else.

Special File Handling

File	Output
`about.md`	Renders the full `AboutOutput` neofetch-style bio panel (see `whoami`)
`references.log`	Renders three timestamped `[INFO]`/`[WARN]` log entries inline
Any other file	Prints the node’s `content` string, whitespace-preserved

Examples

Read the references log:

cat references.log

[2023-10-24 14:32:01] INFO: "Incredible developer, shipped our MVP in record time." - CEO, StartupInc
[2022-05-12 09:15:44] INFO: "The cleanest code I've ever reviewed." - Lead Engineer, TechCorp
[2021-11-03 16:45:22] WARN: "Drinks too much coffee, but gets the job done." - Product Manager

Read a project file:

cat projects/terminal-portfolio.md

project:terminal

Read the about file (renders the bio component):

cat about.md

This is identical to running whoami.

Error Cases

No argument supplied:

cat

cat: missing operand

Path does not exist:

cat readme.txt

cd: readme.txt: No such file or directory

Targeting a directory:

cat projects/

cat: projects/: Is a directory

Overview

Terminal Commands

Components

Customization

ls, cd, and cat — Terminal Filesystem Navigation Commands

The Virtual Filesystem

`ls` — List Directory Contents

Syntax

Description

Examples

Error Cases

`cd` — Change Directory

Syntax

Description

Supported Path Forms

Examples

Error Cases

`cat` — Read File Contents

Syntax

Description

Special File Handling

Examples

Error Cases

Build docs developers (and LLMs) love

Overview

Terminal Commands

Components

Customization

Documentation Index

​The Virtual Filesystem

​ls — List Directory Contents

​Syntax

​Description

​Examples

​Error Cases

​cd — Change Directory

​Syntax

​Description

​Supported Path Forms

​Examples

​Error Cases

​cat — Read File Contents

​Syntax

​Description

​Special File Handling

​Examples

​Error Cases

Build docs developers (and LLMs) love

The Virtual Filesystem

`ls` — List Directory Contents

Syntax

Description

Examples

Error Cases

`cd` — Change Directory

Syntax

Description

Supported Path Forms

Examples

Error Cases

`cat` — Read File Contents

Syntax

Description

Special File Handling

Examples

Error Cases