# Files and port forwarding

> Browse, inspect, search, create, delete, copy, and sync files on any Computer, or forward TCP ports with v42 ls, stat, find, mkdir, rm, cp, sync, and forward.

Every file command in `v42` accepts either a local path or a remote path in `<computer>:/absolute/path` form (`<computer>` is a Computer ID or name). File operations run over the dedicated `file` channel so they never slow down active terminals.

## Listing, inspecting, and searching files

```sh
v42 ls [-a] [-l] <location>
v42 stat [--no-follow] <location>
v42 find <location> <query> [--limit <limit>]
```

- `ls <location>`: List a directory. Folders come first, then files, in natural name order. Up to 10,000 entries are returned (when more exist, `.data.truncated` is `true`).
  - `-a`, `--all`: Include entries whose names start with `.`.
  - `-l`, `--long`: Return each entry as an object with `name`, `kind` (`file`, `dir`, `symlink`, `other`), `size`, and `mtime_ms`. (Use `v42 stat --no-follow` when you need `mode` permissions.)
- `stat <location>`: Show metadata for a single file or directory.
  - `--no-follow`: Describe a symbolic link itself instead of its target, and include file permissions (`mode`).
- `find <location> <query>`: Case-insensitive substring search on file names below `<location>`. Entries starting with `.` and `node_modules` directories are skipped. The search stops after `--limit <limit>` matches (`1` to `200`, default `200`), 20,000 visited entries, or 2 seconds, setting `truncated: true` when stopped early.

## Creating and deleting directories and files

```sh
v42 mkdir [-p] <location>
v42 rm [-r] [--yes] <location>
```

- `mkdir <location>`: Create a directory locally or on `<computer>`.
  - `-p`, `--parents`: Create missing parent directories too, and succeed when the directory already exists.
- `rm <location>`: Delete a file, symbolic link, or directory. Symbolic links are removed themselves, never their target.
  - `-r`, `--recursive`: Delete a directory together with everything inside it (requires `--yes`). Without `--yes`, nothing is deleted and the command fails with `confirmation_required` (exit `2`), reporting in `error.details` how many entries would be deleted.
  - The filesystem root (`/`), the user's home directory, and parent directories above home are **always refused**.

## Copying and synchronizing files

```sh
v42 cp [-r] [--restart] <source> <destination>
v42 sync [--delete] [--restart] <source> <destination>
```

`<source>` and `<destination>` can be local paths or `<computer>:/absolute/path` coordinates in any combination (local to remote, remote to local, or Computer A to Computer B).

- `cp`: Copy a file or directory.
  - `-r`, `--recursive`: Copy a directory and its contents recursively. If `<destination>` is an existing directory, the source's base name is created inside it.
  - `--restart`: Discard interrupted partial transfers for this operation and start over from the beginning.
- `sync`: Synchronize the contents of `<source>` directory into `<destination>` directory in one direction.
  - By default, extra entries in `<destination>` are **kept**.
  - `--delete`: Delete destination entries that are not in `<source>`. Deletion runs only after all copies succeed and the source manifest is verified unchanged.
  - `--restart`: Discard interrupted partial transfers and start over.
  - `cp` and `sync` refuse a destination that is, contains, or is inside the source on the same machine (`invalid_argument`). Paths are compared ignoring letter case, and a local path counts as the same machine as `<this computer>:/path` when `v42` signs in through that Computer's Vibe42.

### Transfer integrity and resume

Files are verified with both per-chunk and whole-file SHA-256 checksums, written to a `.part` file first, and committed atomically only after verification passes. If a transfer is interrupted, running the same `cp` or `sync` command again resumes from the saved offset. If the source file changed in the meantime, the command fails with `resume_source_changed`; pass `--restart` to copy from the start.

## Port forwarding (`v42 forward`)

```sh
v42 forward <computer>:<remote-port> [<local-addr>:]<local-port>
```

Listens on a local TCP port and forwards incoming connections over an end-to-end encrypted tunnel to `127.0.0.1:<remote-port>` on `<computer>`:

```sh
v42 forward my-mac:3000 3000
v42 forward my-mac:5432 127.0.0.1:15432
v42 forward my-mac:3000 0
```

- When `<local-addr>` is omitted, the listener binds to `127.0.0.1` only. Binding to a non-loopback address prints a warning on stderr.
- Setting `<local-port>` to `0` lets the OS pick a free port; once ready, the listener writes a `forward_listening` JSON notice to stderr with the bound address and port.
- Up to **64** simultaneous TCP connections are supported, preserving TCP half-close semantics.
- Stop forwarding with `Ctrl+C` (`SIGINT`) or `SIGTERM`. Relayed traffic counts toward [Credits and usage](/docs/account/credits-and-usage) when the connection runs through an AP.
