# Command line

Every command of the silan command-line client, its arguments and exit codes.

The `silan` command is the command-line client of the engine. It ships inside the app at `/Applications/Silan.app/Contents/Helpers/silan` and is not put on your PATH.

```text
silan [--url URL] [--key KEY] [--json] <command> [arguments]
```

`--json` prints the engine's reply as JSON instead of words. The engine address comes from `--url`, `SILAN_URL`, or `~/Library/Application Support/Silan/engine.json`. The key comes from `--key`, `SILAN_API_KEY`, or the engine's local key file that `engine.json` names (an engine on this Mac only). A lease token comes from `--lease` or `SILAN_LEASE`.

## Devices

| Command | What it does |
|---|---|
| `devices [--platform ios\|android] [--kind K] [--label L] [--state S]` | List devices |
| `device <device>` | One device with its capabilities and health |
| `observe <device> [--elements interactive\|all\|none] [--save FILE]` | A screenshot and the element list |
| `screenshot <device> [-o FILE] [--format png\|jpeg]` | The screen as an image |
| `tap <device> TARGET [--count 2\|3]` | Tap a target |
| `long-press <device> TARGET [--duration MS]` | Touch and hold |
| `type <device> <text> [TARGET] [--clear] [--submit]` | Type text |
| `press <device> <home\|lock\|back\|volumeUp\|volumeDown\|...>` | Press a hardware button |
| `key <device> <enter\|backspace\|tab\|...> [--modifiers command,shift] [--repeat N]` | Press a key |
| `swipe <device> <up\|down\|left\|right> [--speed slow\|medium\|fast]` | Swipe |
| `launch <device> <app id> [--fresh]` | Open an app |
| `terminate <device> <app id>` | Close an app |
| `open-url <device> <url>` | Open a link |
| `wait <device> QUERY [--gone] [--timeout MS]` | Wait for an element to show or go |
| `claim <device>... [--ttl SECONDS] [--wait MS]` | Claim devices (a lease) |
| `claim --platform ios [--count N]` | Claim by selector |
| `release <lease id>` | Give a lease back |

`TARGET` is one of `--text T`, `--id IDENTIFIER`, `--role ROLE`, `--description D` (with `--match exact|contains|regex|caseInsensitive` and `--index N`), `--ref e12@snap_7f3a`, or `--at X,Y [--space pixels|points|normalized]`. `QUERY` is the same without `--ref` and `--at`.

## Scenarios

Scenarios from the command line are a preview that is not tested yet. Do not rely on them in CI.

| Command | What it does |
|---|---|
| `run <scenario.silan.yaml> [--bind role=device]... [--param name=value]... [--junit FILE] [--html FILE] [--report-json FILE] [--no-record] [--timeout SECONDS]` | Run a scenario, follow it, write the reports; exit 0 only when it passed |

## Safety and admin

| Command | What it does |
|---|---|
| `stop` | Stop Everything: halt every action on every device and hold every task and run |
| `resume` | Let held tasks and runs go on |
| `approvals [--state pending\|approved\|denied\|expired]` | List approvals |
| `approvals approve\|deny <approval id> [--remember once\|thisTask\|thisChat\|thisSiteForAnHour]` | Answer an approval |
| `keys create --name NAME --scope SCOPE... [--device ID]... [--profile core\|testing\|full] [--policy-profile NAME] [--expires ISO-8601]` | Make an API key. Answers `403` on the current release: making a key needs the admin right, so make keys on the **Connections** page |
| `keys list` | List keys |
| `keys revoke <key id>` | Revoke a key. Answers `403` on the current release: revoke keys on the **Connections** page |

## Other

| Command | What it does |
|---|---|
| `health` | Engine liveness and component status |
| `version` | Engine, API and MCP protocol versions |
| `call <operationId> [name=value]... [--body JSON\|@FILE\|-] [-o FILE]` | Any REST operation by its id; `silan call --list` names them |
| `mcp [--profile core\|testing\|full]` | The stdio MCP server for AI apps (over XPC; with `--key`, the engine's `/mcp`) |

## Exit codes

| Code | Means |
|---|---|
| 0 | success |
| 1 | failed |
| 2 | usage |
| 3 | no engine |
| 4 | key refused |