# Reading a repository without a clone

`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](/docs/sparse-clones) 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.

```bash
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`](/docs/cli#oak-diff). See the [CLI reference](/docs/cli#oak-ls-cat-grep) for every flag.