oak ls, oak cat and oak grep read a repository on the server. They don't change your branch, your refs or your files, so they work from any directory that is linked to the repository, including a sparse clone that doesn't hold the path you want. All three need --remote; there is no local oak ls.
The server filters what it returns by what you can read. A path you can't read is absent, as if it didn't exist.
oak ls --remote # the repository root on main
oak ls --remote src/api --rev my-branch --json
oak cat --remote src/api/mod.rs --rev my-branch
oak grep --remote "verify_token" --json -- src/auth
oak grep --remote -E "fn (read|write)_" --case-sensitive
ls#
oak ls --remote [PATH] [--rev BRANCH_OR_HASH] [--max-entries N] [--json] lists one directory. --rev takes a branch name or a full 64-character commit hash (an abbreviated hash is refused, since it can't be resolved unambiguously on the server). --max-entries defaults to 1000; the JSON says truncated when it stopped early.
cat#
oak cat --remote PATH [--rev BRANCH_OR_HASH] [--max-bytes N] [--json] prints one file, checked against the commit's recorded content hash. A file larger than --max-bytes (default 16 MiB) is reported, not printed.
grep#
oak grep --remote PATTERN [-E] [--case-sensitive] [--max-files N] [--json] [-- PATH...] searches the server's copy of main. It is case-insensitive unless you pass --case-sensitive, and -E reads the pattern as a regular expression. Paths after -- limit the search to those prefixes. It stops after --max-files matching files (default 100) and exits 1 when nothing matches.
What is verified#
oak cat --remote verifies the bytes it prints. ls and grep results are redacted by the server rather than proved, so their JSON says "verified": false. Treat a listing or a search hit as a pointer, and cat the file when the content matters.
To compare two commits without checking them out, see oak diff --remote. See the CLI reference for every flag.