# framesmith-cli
Command-line tool for controlling Samsung Frame TVs over your local network — no cloud, no Samsung account.
Manage artwork, display settings, slideshows, mattes, filters, and more from your terminal. Powered by the [`framesmith`](https://crates.io/crates/framesmith) library.
## Installation
```sh
cargo install framesmith-cli
```
This installs the `framesmith` binary.
## Quick Start
### Find Your TV
```sh
framesmith discover
```
> Discovery uses SSDP multicast and only finds TVs on the same subnet.
### Pair with the TV
```sh
framesmith 192.168.1.100 auth
# Approve the connection prompt shown on the TV screen
# Token is saved to ~/.framesmith/token (customize with -t/--auth-token-file)
```
### Upload and Display Art
```sh
framesmith 192.168.1.100 art upload ~/dogs-playing-poker.png --select
```
> **Tip:** The TV hostname is the first argument by design — create an alias for TVs you use often:
>
> ```sh
> alias livingroom="framesmith 192.168.1.100"
> livingroom art upload --select ~/dogs-playing-poker.png
> ```
## Commands
### Art Management
```sh
# List all images on the TV
framesmith <HOST> art list
# Show info for the currently displayed image
framesmith <HOST> art show-info
# Show info for a specific image
framesmith <HOST> art show-info MY_F0001
# Upload an image (optionally display it immediately)
framesmith <HOST> art upload photo.jpg --select
# Upload, display, and delete the previous image
framesmith <HOST> art upload photo.jpg --replace-selected
# Center a small image on a colored canvas
framesmith <HOST> art upload small.png --canvas black
framesmith <HOST> art upload small.png --canvas "#1a1a2e"
# Select / delete images
framesmith <HOST> art select MY_F0001
framesmith <HOST> art delete MY_F0001 MY_F0002
# Download a thumbnail
framesmith <HOST> art thumbnail MY_F0001 -o thumb.jpg
# Toggle favorite
framesmith <HOST> art favorite MY_F0001 on
```
### Art Mode & Slideshows
```sh
framesmith <HOST> art mode on
framesmith <HOST> art mode off
framesmith <HOST> art mode status
framesmith <HOST> art slideshow on --duration 300 --shuffle --category favorites
framesmith <HOST> art slideshow status
framesmith <HOST> art slideshow configure --duration 120 --shuffle off
framesmith <HOST> art slideshow off
```
### Mattes & Filters
```sh
framesmith <HOST> art matte list
framesmith <HOST> art matte set MY_F0001 flexible_dx_moderate
framesmith <HOST> art filter list
framesmith <HOST> art filter set MY_F0001 ink_wash
```
### Display Settings
```sh
framesmith <HOST> display brightness 7
framesmith <HOST> display color-temp 2
framesmith <HOST> display auto-brightness on
framesmith <HOST> display rotation
```
### Motion Sensor
```sh
framesmith <HOST> motion timer 30 # minutes: off, 5, 15, 30, 60, 120, 240
framesmith <HOST> motion sensitivity high # low, medium, high
```
### Remote Control
```sh
framesmith <HOST> remote power-off
framesmith <HOST> remote home
framesmith <HOST> remote vol-up
framesmith <HOST> remote hdmi1
framesmith <HOST> remote play
```
40+ buttons available: power, navigation, volume, channels, media playback, number keys, color keys, HDMI inputs, and more.
### Device Info
```sh
framesmith <HOST> info # no auth required
```
## Background Server
By default, the CLI routes commands through a background server process that holds a persistent WebSocket connection to the TV. This avoids the several-second connection setup (TLS handshake, auth exchange, protocol negotiation) on every invocation — once a server is running, commands execute nearly instantly.
The server starts automatically on the first command that needs it. Manage it explicitly with:
```sh
framesmith <HOST> server start
framesmith <HOST> server stop
framesmith <HOST> server restart
framesmith <HOST> server status
framesmith <HOST> server tail-logs
```
### Direct Mode
Use `--direct` to bypass the background server and connect to the TV directly. Useful for scripting, one-off commands, or environments where background daemons are unwelcome.
```sh
framesmith <HOST> --direct art list
```
## Global Options
| `-t, --auth-token-file <PATH>` | Path to the auth token file | `~/.framesmith/token` |
| `--timeout <SECONDS>` | TV initial-connection timeout | `5` |
| `--direct` | Bypass background server, connect directly to TV | off |
| `--json` | Emit all output as JSON | off |
| `-v, --verbose` | Enable debug logging | off |
## Network Requirements
- Your machine and the TV must be on the **same subnet** (or use [SNAT masquerading](https://github.com/jeffmo/framesmith#cross-subnet--cross-vlan-access) for cross-VLAN setups)
- Ports **8001** (HTTP) and **8002** (WSS)
- The TV must be powered on or in Art Mode / standby with network standby enabled
## Library
Looking for a Rust library? See [`framesmith`](https://crates.io/crates/framesmith).
## License
MIT