Files and paths

Applies to: Rubian 4.0.2; path behavior depends on the supplied build

Updated September 16, 2026

Rubian exposes directories and files through familiar command names. Use explicit paths when an operation must select a particular file. A provisioned environment can expose both Rubian-managed locations and host locations; the same-looking path need not identify the same resource in every build or session.

Command reference#

Command	Arguments and result	Notes
`pwd`	No arguments. Prints and returns the current path.	Check this before a relative-path operation.
`cd(path)`	Optional string. Changes the working location; returns `nil`.	`cd` with no argument returns to the configured host home. `cd('..')` moves toward the parent. A failed lookup prints a diagnostic.
`ls(path = nil)`	Optional string. Prints a listing and returns entry names.	With no path, lists the current location. A failed host-directory lookup returns `nil`; an empty result can be an empty array.
`cat(*paths, quiet: false)`	One or more path strings. Returns text from successful reads, or `nil` when no content was obtained.	Multiple successful contents are joined with a newline. `quiet: true` suppresses normal display.
`file(*paths)`	Displays file-type information for the selected files and returns `nil`.	Supports host files and available managed-file information. Use it for inspection, not as a content-validation guarantee.

Navigate deliberately#

pwd
cd('/path/to/workspace')
pwd
ls

Substitute a directory supplied for your evaluation. Check the second pwd before continuing: the printed message from cd may have explained that the requested location was unavailable. cd does not return a Boolean success result.

Bare names can be resolved against locations known to the environment. That convenience is useful interactively, but it can make a repeated operation ambiguous. Prefer a complete path in automation and keep the environment's mount and access configuration with the procedure.

Read one file or several#

body = cat('/path/to/example.txt', quiet: true)
puts body if body

For several files:

combined = cat('/path/to/first.txt', '/path/to/second.txt', quiet: true)

The combined result can contain only the files that were read successfully. It is not proof that every requested file existed. If completeness matters, read and check each path separately before processing the combined data.

Copy, move and create#

The available operations differ between host files and Rubian-managed files. A familiar command name does not imply identical filesystem support.

Command	Host files	Rubian-managed files
`cp(source, destination)`	Copies one regular file. A destination directory keeps the source basename.	Supports a file copy within the managed filesystem. Copies between host and managed files are unsupported.
`mv(source, destination)`	Moves a file using the host operation.	Not supported by this command.
`mkdir(path)`	Creates one directory.	Creates one managed directory. Neither form is a recursive parent-directory creation interface.
`touch(*paths)`	Creates an empty file or updates an existing file's timestamps.	Writes empty content; it can truncate an existing file.
`rm(path)`	Deletes the selected file.	Deletion is not implemented by this command.
`rmdir(path)`	Removes an empty directory.	Deletion is not implemented by this command.
`ln(source, destination)`	Creates a hard link; pass `'-s'` first for a symbolic link.	Managed links are not supported.

cp does not recursively copy a directory. Most of these commands report errors and return nil, so verify the resulting path and contents rather than testing nil as a success flag. Deletion does not move a file to a recovery bin.

For a host-file copy, choose a destination that is not already valuable:

source = '/path/to/example.txt'
destination = '/path/to/example-copy.txt'
cp(source, destination)
copy = cat(destination, quiet: true)
puts copy if copy

Do not use touch on an existing managed file when the intention is merely to update its timestamp. Use the editor for a deliberate content change.

Write and append text#

append(source, destination) appends to a host or managed file. The source can be a file or literal text; if it identifies a known file, that file's content is used. It adds a terminating newline as needed. Supply the destination as the second argument, and use an explicit source path when copying content from a file.

tee(content, file, append: false) writes a host file, displays the content and returns the original value. It replaces the destination by default. Use append: true to add content:

tee("Review complete", '/path/to/review.txt')
tee("Next: verify the copied files", '/path/to/review.txt', append: true)

For prompted writing or a saved editing buffer, use Editing and archives. For file mode and ownership changes, use Accounts and permissions.

Empty, missing and inaccessible locations#

An empty listing is different from a failed lookup. For a file read, retain the diagnostic from a non-quiet call when you need to distinguish a missing file, directory or access problem. A quiet call is appropriate after the path is known, but is less useful during initial diagnosis.

If the contents differ from what you expected, confirm the session, current path and intended location before writing anything. Report the supplied build and the exact command to the environment administrator. Do not treat a path shown in a website example as a path installed on your machine.