Frames CLI: Apple device frames for screenshots and video
frames-cli
The frames CLI puts screenshots and screen recordings into official Apple bezels and detects the device from the frame size
- 448 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The CLI downloads the bezel pack from cdn.macstories.net and runs `ffmpeg` and `ffprobe` on your files
- The result is written next to the source files and can replace same-named `_framed` files
Install
- Works in
Manual install
git clone https://github.com/viticci/frames-cli.git && cd frames-cli && pip3 install PillowThen link the `frames` file into a directory on your PATH, for example `ln -s "$(pwd)/frames" ~/.local/bin/frames`, and run `frames setup`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The CLI downloads the bezel pack from cdn.macstories.net and runs `ffmpeg` and `ffprobe` on your files
- The result is written next to the source files and can replace same-named `_framed` files
This is third-party code. Review the repository files before installing.
What it does
`frames` is a single-file Python CLI. It takes a screenshot or a screen recording, detects the device from the pixel size and puts an Apple bezel in the chosen body color around the frame. When several devices share a size, the newest generation wins, and the `--device` flag picks another. The result is saved next to the source as `name_framed.png`. Images are processed in batches: `frames *.png` or a whole folder. Colors are set with `-c` by name or number, `-c random` picks a color for each file separately and `--colors` assigns colors as a list. The `-m` flag merges several frames into one. Videos go through `frames video`: `.mp4`, `.mov` and `.m4v`, with audio kept unless `--strip-audio` is passed. The `compact`, `balanced` and `best` presets change size and quality, and `--alpha` or `--codec hevc-alpha` give a transparent background. The bezels are not stored in the repository: `frames setup` downloads the Apple Frames 4 pack of about 50 MB. The pack covers iPhone 18 Pro, iPhone 18 Pro Max, iPhone Duo and MacBook Pro with the PROLED display. The repository also holds `skill/SKILL.md`, which explains the commands to an agent, the `--json` flag for automation and diagnostics through `frames doctor`.
Who it is for. iOS app authors and reviewers who need screenshots and screen recordings in Apple device bezels for a website, an app store page or an article.
Good fit when
- An app page needs screenshots in an iPhone 18 Pro bezel with a choice of body color
- A folder of dozens of screenshots should get bezels with one command
- Two screen recordings have to sit side by side in one clip: at once or one after another from left to right
- A clip with a transparent background is needed for editing or a presentation
- An agent detects the device from the screenshot size and returns the result as JSON
Not a fit when
- The bezels are needed for devices outside the Apple Frames pack: the model list comes from the installed pack and `frames list` shows it
- The background must be more complex than white, black, a hex color or transparent: the CLI draws no other canvas
- Video is processed on a machine without `ffmpeg` and `ffprobe` 5.1: they are required for clips
Example request
Put all screenshots from the Screenshots folder into iPhone 18 Pro bezels in Silver and save the result into a framed folderLimitations
Python 3.8 and Pillow are required. Video needs `ffmpeg` and `ffprobe` 5.1 or newer, and transparent HEVC works only on macOS with an ffmpeg build that has VideoToolbox. ProRes 4444 files are noticeably larger than the source clip.
The bezel pack is downloaded from cdn.macstories.net with `frames setup`; its path is stored in `~/.config/frames/config.json` or in the `FRAMES_ASSETS` variable. The iPhone Duo sizes were verified in the Xcode 27.1 simulator and not on a device. The project is based on the Apple Frames shortcut from MacStories and is not affiliated with Apple.
How to disable. Delete the `~/.local/bin/frames` link and the cloned `frames-cli` folder. The bezel pack sits at the path from `~/.config/frames/config.json` and can be deleted separately.
FAQ
How do I install Frames CLI?
Run `git clone https://github.com/viticci/frames-cli.git`, then `pip3 install Pillow` and link the `frames` file into a directory on your PATH, for example `~/.local/bin`. Check `frames --version` and run `frames setup` to download the bezels.
How do I connect Frames CLI to Claude Code?
Copy `skill/SKILL.md` from the repository into the agent's skills folder, for example `~/.claude/skills/frames-cli/`. The README has no separate skill install command.
Which devices can the CLI frame?
The list depends on the downloaded pack. The Apple Frames 4 pack includes iPhone 18 Pro and 18 Pro Max, iPhone Duo and MacBook Pro with PROLED. `frames list` prints the exact names.
How do I make a clip with a transparent background?
For a compressed file on macOS use `frames video --codec hevc-alpha recording.mp4`; for editing, `--alpha` gives ProRes 4444 in `.mov`. The output path for both codecs must end in `.mov`.
Does the CLI work without ffmpeg?
Images are processed without it. Video needs `ffmpeg` and `ffprobe` 5.1 or newer, and `frames doctor` shows whether the toolset is ready.
Discussion
No questions or reviews yet.
Related
CLI toolsA skill set for writing video in TypeScript and rendering it on the GPU with no browser: compositing, motion graphics, 3D.
A CLI that shrinks a video to an exact size locally with FFmpeg and reports VMAF and SSIM quality scores, with a skill for agents
Claude Code skill that turns raw talking-head clips into a finished Instagram reel, picks the best takes and cuts dead air
FrameJam lets an agent build videos in a chosen style and take edits from a click on a frame with a timestamp
Skills and CLI from HeyGen: the agent writes HTML compositions and renders them into MP4 videos, captions, motion graphics and decks
A skill and CLI that let Claude Code or Codex make videos as web pages, with the Studio editor to change the result
README in short
The README covers installation, downloading the bezel pack, size tables for iPhone 18 Pro, iPhone Duo and MacBook Pro with PROLED, and a quick start with colors, batch processing and merging. Further sections cover video and settings. MIT license.