File

The file command creates, reads, updates, and deletes files against local or remote backends. The same commands work against any backend Trilogy knows about.

Only the local filesystem ships today. Future releases will add cloud storage and remote git model backends, so scripts and agent loops written against trilogy file keep working when the backend changes - which is the reason to prefer it over ad-hoc shell or Python plumbing.

The other reason is validation: writing a .preql file through this command parses it first, so a truncated or HTML-escaped body cannot land silently.

Usage

trilogy file list [path] [options]
trilogy file read <path>
trilogy file write <path> [options]
trilogy file move <src> <dst>
trilogy file delete <path> [options]
trilogy file exists <path>

trilogy file list

Lists files at a path, defaulting to the current directory. The default view surfaces just the .preql model files and their leading description comments, the same one-line purpose strings the agent's list_files tool shows.

Option	Description
-r, --recursive	Recurse into subdirectories.
-l, --long	Show size and entry kind alongside the path.
-a, --all	Show every entry, not just .preql files and directories.

trilogy file list
trilogy file list models/ -r -l
trilogy file list . --all

trilogy file read

Reads the file at a path and writes its contents to stdout.

trilogy file read raw/orders.preql

trilogy file write

Writes or overwrites a file. Content is taken from --content, --from-file, --from-url, or stdin, in that order.

Option	Description
-c, --content TEXT	Inline content. Omit the flag, or pass -c with no value, to read stdin.
--from-file FILE	Copy bytes from a local file.
--from-url TEXT	Fetch bytes from an http(s):// or file:// URL.
-e, --escapes	Interpret backslash escapes (\n, \t, \\, \xNN) in --content.
--no-create	Fail if the target file does not already exist (update only).
-f, --force	Skip Trilogy syntax validation for .preql files.
-q, --quiet	Suppress success output.

# From stdin
cat model.preql | trilogy file write raw/orders.preql

# Inline, with escapes - useful on shells without heredocs
trilogy file write notes.txt -c "line one\nline two" --escapes

# From a raw gist, the "copy this snippet" flow
trilogy file write raw/orders.preql --from-url https://gist.githubusercontent.com/.../orders.preql

# Skip validation for a partial draft
trilogy file write raw/wip.preql --from-file draft.preql --force

.preql targets are parsed before the write lands. Use --force only for drafts you intend to finish editing in place.

trilogy file move

Moves or renames a file.

trilogy file move raw/orders.preql raw/sales_orders.preql

trilogy file delete

Deletes the file or directory at a path.

Option	Description
-r, --recursive	Recursively delete directories.
-f, --force	Do not error if the path does not exist.

trilogy file delete raw/scratch.preql
trilogy file delete build/ -r -f

trilogy file exists

Exits 0 if the path exists, 1 otherwise. Prints nothing, so it composes cleanly in scripts.

trilogy file exists trilogy.toml && echo "workspace ready"