> ## 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, download, 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.

`files cat` returns text: a file over 5 MB, or one that isn't UTF-8 text (an image, an archive, a
database file), is refused. Use `files download` for those.

## Download a File

```bash theme={null}
instapods files download my-app /home/instapod/app/data/app.db
instapods files download my-app backup.tar.gz --output ~/backups/
instapods files download my-app logs/app.log --output - | grep ERROR
```

Saves a file from the pod to your machine, byte for byte. It works for any size and any type of
file. The path is absolute, or relative to the pod's app root.

| Flag | Description | Default |
| - | - | - |
| `-o`, `--output` | Local file or directory to save to. `-` writes to stdout | The file's own name, in the current directory |
| `--force` | Overwrite the local file if it already exists | `false` |

An existing local file is never overwritten unless you pass `--force`. A download that fails or is
interrupted leaves nothing behind: the file only appears under its final name once the whole
transfer has succeeded (and with `--force`, the file being replaced is kept until then).

It downloads one file. To fetch a directory, archive it in the pod first and download the archive:

```bash theme={null}
instapods exec my-app -- tar czf /tmp/data.tar.gz -C /home/instapod/app data
instapods files download my-app /tmp/data.tar.gz
```

A symbolic link is refused with the path it points to; download that path instead.

## 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.

> [!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.


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