> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instapods.com/llms.txt
> Use this file to discover all available pages before exploring further.

# File Management

> Manage pod files from the CLI — list, read, write, upload, and sync.

The `instapods files` commands let you manage files inside your pods without SSH.

## List Files

```bash theme={null}
instapods files ls my-app
instapods files ls my-app /home/instapod/app/src
```

Lists files and directories. The path argument is optional and defaults to the pod's app root.

Output includes file name, size, and permissions.

## Read a File

```bash theme={null}
instapods files cat my-app /home/instapod/app/index.js
```

Outputs the file contents to stdout.

## Write a File

```bash theme={null}
instapods files write my-app /home/instapod/app/config.json --content '{"key": "value"}'
```

Creates or overwrites a file with the given content. You can also pipe content via stdin:

```bash theme={null}
cat .env | instapods files write my-app /home/instapod/app/.env
echo "Hello!" | instapods files write my-app /home/instapod/app/hello.txt
```

## Create a Directory

```bash theme={null}
instapods files mkdir my-app /home/instapod/app/src
instapods files mkdir my-app /home/instapod/app/data/uploads -p
```

Use `-p` to create parent directories recursively (like `mkdir -p`).

## Upload a File

```bash theme={null}
instapods files upload my-app ./index.html
instapods files upload my-app ./dist/bundle.js --remote /home/instapod/app/public/bundle.js
```

Uploads a local file to the pod. If `--remote` is not specified, the file is placed in the pod's app root with the same filename.

`--remote` takes either an absolute path or one relative to the app root, and it can rename the
file on the way in:

```bash theme={null}
# relative to the app root
instapods files upload my-app ./dist/bundle.js --remote public/bundle.js

# renamed on arrival
instapods files upload my-app ./build/index.prod.html --remote index.html
```

## Sync a Directory

```bash theme={null}
instapods files sync my-app --local ./my-project
```

Recursively uploads an entire local directory to the pod. Shows progress with checkmarks for each file uploaded.

A directory of any size works. The API accepts 100 MB per request, so `files sync` groups files
into batches under a 64 MB budget and sends them one after another - you don't need to split a
large project into subdirectory syncs by hand. Files whose content already matches what's on the
pod are skipped, so a repeat sync only sends what changed.

`--dry-run` prints the total size as well as the file count, and tells you up front when the
transfer will be chunked:

```
Total: 42 directories, 318 files, 275.4 MB
Over the 64 MB per-request budget — will be uploaded in chunks.
```

### Sync Flags

| Flag | Description | Default |
| - | - | - |
| `--local` | Local directory path | Current directory (`.`) |
| `--remote` | Remote directory path | Pod's app root |
| `--exclude` | Glob patterns to exclude (repeatable) | `node_modules`, `.git`, `.env`, `__pycache__`, `.DS_Store` |
| `--dry-run` | Preview what would be uploaded | `false` |

### Examples

```bash theme={null}
# Sync current directory (simplest form)
instapods files sync my-app

# Sync with additional exclusions
instapods files sync my-app --local ./project \
  --exclude "*.log" \
  --exclude "vendor"

# Preview before syncing
instapods files sync my-app --local ./project --dry-run

# Sync to a specific remote path
instapods files sync my-app --local ./build --remote /home/instapod/app/public
```

<Note>
  Common patterns like `node_modules`, `.git`, `.env`, `__pycache__`, and `.DS_Store` are excluded by default. Add `--exclude` flags for any additional patterns you want to skip.
</Note>

<Warning>
  **PHP preset**: The web root is `/home/instapod/app/public`, not `/home/instapod/app`. Upload your public-facing files (index.php, CSS, JS) to the `public/` subdirectory, and application logic to the app root.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.