Get Started with CookieOS

This guide walks you through everything you need to know to be productive with CookieOS straight away: reading the boot screen, navigating the Start Menu, browsing the filesystem with the built-in File Explorer, writing your first script that uses the cosUtils API, and inspecting system information with screenfetch. By the end you will have a solid mental model of how the OS is structured and how to extend it with your own Lua programs.

Boot into CookieOS

Power on your CC:Tweaked computer (right-click it in the world). The boot sequence runs automatically:

The screen clears to black.
A yellow version watermark — CookieOS v2.2.5 — appears centred near the middle of the screen.
An animated blue loading bar fills beneath the watermark. In development mode a countdown timer (e.g. 1.23s) is shown below the bar as it progresses.
The bar reaches 100 %, the screen clears, and the Start Menu appears.

The menu bar at the top of every CookieOS screen always shows the version string on the left and a live 12-hour clock on the right. Both update automatically.

Navigate the Start Menu

The Start Menu is a centred box listing five options. Use the keyboard to move through them:

Key	Action
`↑` Up Arrow	Move selection up (wraps to bottom)
`↓` Down Arrow	Move selection down (wraps to top)
`Enter`	Confirm the highlighted option

The currently selected option is displayed with square brackets, for example [ Command ]. The five menu options are:

Option	What it does
Command	Opens an enhanced interactive shell (`os/.command`)
Programs	Opens the Programs submenu with built-in apps
Power	Opens the power-management screen (reboot / shutdown)
Uninstall	Removes all CookieOS files and reboots to vanilla CC:Tweaked
Help	Runs the `.help` file

After any program launched from the menu exits, the computer returns to the Start Menu automatically.

Launch the File Explorer

From the Start Menu, select Programs and press Enter. The Programs submenu lists:

File Explorer
Play Music (red if no speaker peripheral is attached)
Chat (red if no chatBox peripheral is attached)
Player Tracker (red if chatBox, monitor, or playerDetector is missing)
Back

Select File Explorer and press Enter. The explorer opens a two-panel layout:

Left panel — lists directories (white, highlighted in light-blue when selected) and files (green) in the current directory. The currently selected entry is prefixed with > .
Right panel — shows metadata for the selected entry: Size, Modified, Created, and Read Only status, provided by the enhanced fs.attributes2() function.

File Explorer keyboard controls:

Key	Action
`↑` / `↓`	Move the selection up or down
`Enter`	Open a directory, or open a file in the `edit` program
`Backspace`	Go back to the previous directory
`F6`	Exit the File Explorer and return to the shell

Use cosUtils in a script

The cosUtils library is loaded into _G.cosUtils at boot time, making it available in every Lua script you write — no require needed. Open the Command prompt from the Start Menu, then use edit to create a new script:

edit myscript.lua

Here is a working example using real cosUtils functions:

-- cosUtils is globally available in all scripts

-- Get a formatted date-time string (12-hour format)
local time = cosUtils.getTime("12")
print(time) -- e.g. "2024-01-15 03:45:22 PM"

-- Append a timestamped message to os/data/OS.log
cosUtils.logToOS("My script started")

-- Wrap code in safeRun to get a BSOD on unhandled errors
-- instead of a raw Lua traceback
cosUtils.safeRun(function()
  -- List all top-level files and directories
  local files, dirs = cosUtils.getFilesAndDirs("/")
  for _, d in ipairs(dirs) do print(d) end
end)

A few commonly used cosUtils functions at a glance:

Function	Description
`cosUtils.getTime(fmt)`	Returns a formatted date-time string. Pass `"12"` or `"24"`.
`cosUtils.logToOS(msg)`	Appends a timestamped entry to `os/data/OS.log`. Auto-rotates at 50 KB.
`cosUtils.safeRun(fn, ...)`	Calls `fn` inside `pcall`; triggers a blue BSOD screen on failure.
`cosUtils.getFilesAndDirs(dir)`	Returns two tables: `files`, `dirs` for the given path, with sizes.
`cosUtils.resetScreen(win)`	Clears a terminal/window and resets colours to white-on-black.
`cosUtils.centerPrint(y, w, text)`	Prints `text` centred horizontally at row `y`.
`cosUtils.BSOD(err, device)`	Displays a Windows-style blue screen with a random memory address, logs the error, then reboots.
`cosUtils.compress(str)`	LZW-compresses a string; returns a `"c…"` or `"u…"` prefixed result.
`cosUtils.getSizeOfCosUtils()`	Returns the number of functions currently in the `cosUtils` table.
`cosUtils.del(name, isDir)`	Deletes a file or directory with a progress print and a size-proportional delay.

Check system info with screenfetch

From the Command prompt, run:

screenfetch

CookieOS ships a custom screenfetch replacement in /programReplacements/screenfetch.lua. It renders ASCII art of a ComputerCraft monitor alongside a system information table that includes:

Computer label (or Untitled Computer)
Type — Standard Computer, Advanced Computer, or Command Computer
Main OS — the underlying CC:Tweaked OS version string
Co-OS — the cosv global (CookieOS v2.2.5)
Runtime — Minecraft version or emulator name if detectable
Lua — the Lua version string (_VERSION)
Host — the _HOST string
Uptime — formatted as hours, minutes, and seconds via os.clock()
Size — total storage used, formatted by fs.attributes2("/")
COS API — number of functions loaded in cosUtils, e.g. 28 functions loaded
Extensions — detected features such as HTTP enabled, CC: Tweaked, debug mode, etc.

developmentMode is set to true in startup/loading.lua. While this flag is set, os.pullEvent is not replaced with os.pullEventRaw, which means Ctrl+T remains active and can terminate any running program. This is useful for killing a script that hangs, but keep it in mind if you are building programs that need to run uninterrupted. Set _G.developmentMode = false (and update the source file) to lock Ctrl+T out.

Getting Started

The Interface

Built-in Programs

Program Replacements

Get Started with CookieOS

Build docs developers (and LLMs) love

Getting Started

The Interface

Built-in Programs

Program Replacements

Documentation Index

Build docs developers (and LLMs) love