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

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

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