File Manager

OcaltQL gives full programmatic control over your namespace's filesystem. Every path used with these verbs must start with /root, /mounted, or /external when a server is bound — see Namespace Storage for how those are structured.

Reading and writing

Example
FILE WRITE "Hello World" TO "/root/hello.txt"
AFTER FILE READ "/root/hello.txt" SET ?content
AFTER EMIT ?content

Binary is bytes, not base64

A binary file read out of the namespace is a bytes value — the actual bytes, the way open(f, "rb").read() gives you bytes in Python or file_get_contents does in PHP. It is not base64, and it is not text that happens to look like data.

Bytes go where bytes belong with no ceremony: written back out with FILE WRITE, sent to the response with EMIT, measured with LENGTH, indexed a byte at a time. Base64 is a transport — what you convert to when a JSON field or a URL cannot carry binary — and it appears only because you asked for it.

Read It, Serve It — No Encoding Anywhere
FILE READ "/root/report.pdf" SET ?bytes
AFTER LENGTH ?bytes SET ?n
AFTER HEADER "Content-Type" AS "application/pdf"
AFTER EMIT ?bytes
(* The response IS the PDF *)

Writing binary — the BASE64 modifier

BASE64 tells FILE WRITE that the content it has been handed is already base64, and that the decoded bytes are what should land on disk. Without it, base64 is written as the literal text it is. This is how a PNG, a PDF, or any other binary arrives in the namespace as a real file, and the encoded form can come from anywhere — a captured screenshot's image_b64, a fetched response, or an ENCODE result.

The modifier goes at the end and works with both spellings: after CONTENT, or after the TO form — FILE WRITE ?png TO "/root/pixel.png" BASE64.

Writing a Real PNG from base64
STRING "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC" SET ?png
AFTER FILE WRITE "/root/pixel.png" CONTENT ?png BASE64
AFTER FILE STAT "/root/pixel.png" SET ?s
AFTER EMIT "wrote " & ?s("size") & " bytes"
(* Emits: wrote 69 bytes — a real 1x1 PNG on disk.
   Without BASE64 the same call writes 92 bytes: the base64 text itself *)
Invalid base64 is refused. Content that is not valid base64 fails with Invalid base64 content. and nothing is written — test !THIS('state') or read !ERROR('message') to catch it. Line breaks inside the base64, and a leading data:image/png;base64, prefix, both count as invalid — strip them before writing.
Binary round-trips. FILE READ returns a string for a text file and a bytes value for a binary one — a PNG read back is the PNG, not null. A bytes value can be written straight out again with FILE WRITE "path" CONTENT ?b (no modifier: it is already binary), measured with LENGTH, indexed a byte at a time with ?b(0), or turned back into text form with ENCODE ?b AS BASE64. The BASE64 modifier is still what you want when the script is holding base64 text — from a screenshot, a fetched response, or an ENCODE result.

Checking and inspecting

Example
FILE EXISTS "/root/hello.txt" SET ?bool
AFTER EMIT ?bool
AFTER FILE STAT "/root/hello.txt" SET ?info
AFTER EMIT ?info

FILE STAT returns an object with exists, is_dir, is_file, size, and modified.

Listing a folder

Example
FILE LIST "/root" SET ?items
AFTER EMIT ?items

FILE LIST returns an array of objects, each with name, is_dir, size, and modified.

Folders

Example
FILE MKDIR "/root/photos"

Moving and copying

Example
FILE MOVE "/root/old.txt" TO "/root/new.txt"
AFTER FILE COPY "/mounted/source.txt" TO "/root/copy.txt"

Deleting

Example
FILE DELETE "/root/hello.txt"

Storage usage

Example
STORAGE USAGE SET ?info
AFTER EMIT ?info

Returns an object with root (used) and mounted (used).

Selections

A selection groups multiple paths together so a batch operation can run across all of them at once.

Selecting specific items
FILE SELECT "/root/file1" AND "/root/folder1" AND "/root/file2" SET ?selarray
Selecting everything in a folder
FILE SELECT ALL "/root/folder" SET ?selarray

Acting on a selection

Example
FILE SELECT "/root/a.txt" AND "/root/b.txt" SET ?selarray
AFTER FILE SELECTION ?selarray COPY TO "/root/backup"
AFTER FILE SELECTION ?selarray DELETE

FILE SELECTION ... COPY TO and ... MOVE TO place every selected item into the destination folder, keeping its original name. FILE SELECTION ... DELETE removes every item in the selection.

Compressing and extracting

Example
FILE SELECT "/root/a.txt" AND "/root/b.txt" SET ?selarray
AFTER FILE COMPRESS ZIP ?selarray TO "/root/archive.zip"
AFTER FILE COMPRESS TAR ?selarray TO "/root/archive.tar"

Public sharing

A file can be made publicly accessible at a generated URL under ocalt.com/shared/, without requiring the visitor to have an Ocalt account.

Example
FILE SHARE "/root/file.mp3" SET ?newpublicurl
AFTER EMIT ?newpublicurl
There is no limit on how many files you may share at once.
Listing and removing shares
FILE SHARE LIST SET ?sharedarray
AFTER FILE UNSHARE "/root/file.mp3"
AFTER FILE UNSHARE ALL

QR Code

The QR verb generates a QR code image from a publicly accessible URL. It only accepts shared file URLs (FILE SHARE) or paths inside /root/sites/ — anything else returns an error directing the user to share the file first or move it to a public folder.

QR from a Shared File
FILE SHARE "/root/report.pdf" SET ?url
AFTER QR ?url SET ?qrpath
AFTER EMIT ?qrpath
QR from a Public Site Path
QR "/root/sites/mysite/index.html" SET ?qrpath
AFTER EMIT ?qrpath
(* The QR encodes https://mysite.ocalt.site/index.html *)
Non-Public URL — Blocked
QR "https://google.com" SET ?qr
OR CATCH ERROR SET ?e
AFTER EMIT ?e("message")
(* "URL not available publicly. Please share the file first
    or place it in a public folder." *)
FTP & External Storage →