# Media uploads Uploading is the one part of the media library a browser tab and the API cannot do for a folder: it reads files off your own machine. ```bash mercemur media upload ./images ``` Directories are expanded one level deep and only renderable assets are taken (`png`, `jpg`, `jpeg`, `gif`, `webp`, `avif`, `svg`, `ico`). One level rather than a recursive walk, because pointing at a project directory would otherwise upload `node_modules`. A file you name explicitly is always taken, whatever its extension. ## The size ceiling is about 1 MB **A photograph straight off a phone or a camera will not fit.** The limit comes from the idempotency ledger, which buffers the whole request body to hash it, not from storage. It applies before the upload route runs. Sizes are checked **before anything is sent**. One oversized file stops the batch: ``` 1 file(s) are over the 1020 KB limit, so nothing was uploaded: ./images/hero-raw.png 4.2 MB Resize them, or pass --skip-oversized to upload the rest ``` Finding this out on file 51 of 200 would leave a half-filled library nobody can reason about, so the whole batch is refused until you decide. ```bash mercemur media upload ./images --skip-oversized ``` Skipped files are then listed by name at the end, not counted. "3 skipped" tells nobody which images are missing from their store. ## See the plan first ```bash mercemur media upload ./images --dry-run ``` ``` would upload 1 file(s): ./images/tiny.png 70 bytes SKIP ./images/big.png 1.0 MB, over the limit ``` A dry run sends nothing and reports oversized files as part of the plan rather than refusing, because seeing what would happen is the reason to ask. ## Running out of storage Uploads spend the store's storage allowance. If one is refused with `storage_quota_exceeded` the batch **stops immediately** rather than sending the rest: ``` the store is out of storage allowance; 12 of 40 uploaded before stopping ``` That refusal never succeeds on retry. The merchant frees space or upgrades, and continuing would spend rate budget to arrive at the answer already in hand. ## Scripting ```bash mercemur media upload ./images --json | jq -r '.uploaded[].url' ``` | Flag | | |---|---| | `--skip-oversized` | Upload what fits and report the rest | | `--dry-run` | List what would be uploaded, send nothing | | `--json` | Machine-readable, with `uploaded` and `skipped_oversized` | Needs the `write_files` scope.