---
name: sam-usage
description: Launch, stop, and list apps on the webOS TV board via sam-cli (/home/root/sam-cli.sh). Use when working with SAM (System Application Manager) on the target board.
---

# sam-cli (SAM on the target board)

`sam-cli.sh` drives SAM (Luna service `com.webos.applicationManager`) on the board.
It lives at `/home/root/sam-cli.sh` — not in PATH, so call it by full path or
prepend `/home/root` to PATH. Use `ssh -tt` for a tty:

```sh
ssh -tt root@172.26.123.126 "/home/root/sam-cli.sh running --ids"
```

## Commands

| Command | What it does |
|---------|--------------|
| `launch <id> ['{"params":{...}}']` | Launch app by id (optional extra JSON merged into payload) |
| `close <id>` | Stop an app by id or instanceId |
| `running [--ids]` | List running apps (ids only with `--ids`) |
| `list` / `list-apps` / `ls` `[--ids]` | List installed apps |
| `status <appId>` | Status of one app |
| `info <appId>` | Info of one app |
| `launch-points` | List launch points |
| `manager-info` | Dev-category managerInfo (needs `--dev`) |

## Flags

- `--dev` — devmode-only `/dev` category (also exposes `close`, `running`, `listApps`)
- `--pretty` — pretty-print JSON (needs jq; not on board → raw JSON)
- `--timeout <secs>` — cap execution (default 30; luna-send replies can take seconds)
- `--wait <secs>` — sleep after `launch`/`close` (slow SSH links)
- `--ids` — print only app ids for `running`/`list`

## Notes

- Output is raw JSON; exit 0 on success, 1 on errors, 2 on missing command.
- `jq` is not installed on the board — built-in fallbacks handle `--ids` and JSON merge.
- Replies arrive after several seconds — prefer a generous `--timeout`.