Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PrinceOfCookies/CookieOS/llms.txt

Use this file to discover all available pages before exploring further.

The filesystem helpers in cosUtils extend CC:Tweaked’s built-in fs API with recursive file counting, byte-accurate directory sizing, human-readable size formatting, name-based file search, filtered and annotated directory listings, safe file reading, and a slow-print file/directory deletion helper. The startup/replacements.lua startup module additionally patches fs.attributes2 onto the fs table, providing enhanced metadata with formatted sizes and human-readable age timestamps.

​
cosUtils.fileCount(directory)

Recursively counts every file (not directory) inside directory, skipping the rom/ path to avoid counting ROM files.
​
directory
string
Path to the directory to scan. Pass "" or "/" for the root of the computer’s filesystem.
Returns a number. 
local count = cosUtils.fileCount("/")
print("Total files: " .. count) -- e.g. "Total files: 47"
cosUtils.loadingBar() calls cosUtils.fileCount("") internally to scale the animation duration, so the boot bar takes longer on more populated computers.

​
cosUtils.getDirectorySize(sPath)

Recursively walks sPath and sums the byte sizes of every file it contains. Directories themselves have no size contribution; only leaf files are counted via fs.getSize().
​
sPath
string
Path to the directory to measure.
Returns a number (total bytes). 
local bytes = cosUtils.getDirectorySize("/os")
print("OS directory: " .. bytes .. " bytes")

​
cosUtils.formatSize(size)

Converts a raw byte count into a concise, human-readable string. The output format depends on magnitude:
RangeFormatExample
≥ 1 MiB (1,048,576 B)"X.XX MB""1.00 MB"
≥ 1 KiB (1,024 B)"X.XX KB""1.50 KB"
< 1 KiB"X B""42 B"
​
size
number
Byte count to format. Coerced with tonumber() before processing.
Returns a formatted string. 
print(cosUtils.formatSize(1536))    -- "1.50 KB"
print(cosUtils.formatSize(1048576)) -- "1.00 MB"
print(cosUtils.formatSize(42))      -- "42 B"

​
cosUtils.getFilesAndDirs(sDir)

Lists the contents of sDir and separates them into two tables: one for files and one for subdirectories. Each entry is a formatted string that includes the item name and its size (via cosUtils.formatSize()). Read-only items are prefixed and suffixed with the middle-dot character · (\xB7). Hidden items (names starting with .) are omitted unless the list.show_hidden CC:Tweaked setting is true.
​
sDir
string
The directory path to list.
Returns tFiles, tDirs — two tables of formatted strings. 
local files, dirs = cosUtils.getFilesAndDirs("/")
-- dirs might contain: { "os (12.34 KB)", "startup (2.10 KB)" }
-- files might contain: { ".menu (1.23 KB)", ".settings (0.05 KB)" }
-- (hidden files only appear when list.show_hidden is true)
The · prefix on read-only entries mirrors the visual style used by the CookieOS File Explorer application.

​
cosUtils.findFile(filename, directory)

Recursively searches for a file whose name exactly matches filename, starting from directory. The search descends into every subdirectory it finds.
​
filename
string
The exact filename to search for (not a pattern).
​
directory
string
default:"/"
The root directory to start the search from. Defaults to "/".
Returns the path string if the file is found, or nil if it is not. 
local path = cosUtils.findFile("cUtils.lua", "/")
print(path) -- "/apis/cUtils.lua"

local missing = cosUtils.findFile("ghost.lua", "/")
print(missing) -- nil

​
cosUtils.readFile(path)

Opens a file in read mode, reads all of its contents, closes the handle, and returns the content string. On failure (e.g. the file does not exist), returns nil and an error message.
​
path
string
Absolute or shell-relative path to the file.
Returns content (string), nil on success, or nil, errorMessage (string) on failure. 
local content, err = cosUtils.readFile("/os/data/OS.log")
if content then
    print(content)
else
    print("Error: " .. err)
end

​
cosUtils.del(name, dir)

Deletes a file or directory with a textutils.slowPrint status message. The delay before deletion is proportional to the item’s size (size in bytes divided by 1000 seconds), simulating a visible deletion process. Before deleting, the function ensures that os/.install is not accidentally removed — if the file is missing from the root, it is moved there first.
​
name
string
Name (or path) of the file or directory to delete.
​
dir
boolean
Pass true if name refers to a directory. Pass false (or nil) for a file.
cosUtils.del("back.lua", false)   -- delete a file
cosUtils.del("startup", true)     -- delete a directory

​
fs.attributes2(path, hdOnly)

fs.attributes2 is patched onto the built-in fs table by startup/replacements.lua at boot. It calls the standard fs.attributes() and then appends three extra fields: a formatted size string, and human-readable modified and created timestamps showing elapsed time (e.g. "2 days, 3 hrs") rather than raw epoch values. If path does not exist as an absolute path, the function automatically resolves it relative to shell.dir().
​
path
string
Path to the file or directory.
​
hdOnly
boolean
default:"false"
If true, timestamps use a condensed two-component format (e.g. "2 days, 3 hrs" or "15 mins, 30 secs"). If false, all non-zero time components from years down to seconds are included.
Returns the standard fs.attributes() table with three additional fields:
FieldTypeExample
sizestring"4.50 KB"
modifiedstring"2 days, 3 hrs"
createdstring"5 weeks, 2 days"
readonlybooleanfalse
local attrs = fs.attributes2("/os")
print(attrs.size)     -- "12.34 KB"
print(attrs.modified) -- "1 day, 2 hrs"
print(attrs.readonly) -- false
For directories, size reflects the recursive total from getDirectorySize(), and modified reflects the most recently modified file inside the directory rather than the directory entry itself.

Build docs developers (and LLMs) love

Get started for freeTalk to us