# Commands

Commands are how you run an output: `in`, `out`, `update`, `invoke` and `timer`. Send them in a batch to [Run commands](https://docs.airframe.tv/api/run-commands) or over the [control WebSocket](https://docs.airframe.tv/api/websocket).

Each command is an object whose `command` says what it does. A batch runs in order, under one revision, and all or nothing: if one command can't run, none do.

```json
{
  "commands": [
    { "command": "update", "component": "lower-third", "data": { "name": "Jane Doe" } },
    { "command": "in", "component": "lower-third" }
  ]
}
```

Components, layers, events, timers and instances are named by **id**. Data is named by each field's **key**. A value of `null` clears a key, so the field goes back to what it inherits or its default.

## in

Puts a component on air, playing its In.

- `component` (string, required): The component's id.
- `data` (object): Values to merge into the component's data first. The component keeps them after it goes off air.
- `instance` (string): An [instance](https://docs.airframe.tv/api/list-instances) of the component to show. Its data replaces the component's data. Send `data` or `instance`, not both.

```json
{ "command": "in", "component": "lower-third", "instance": "4c1d…" }
```

If the component is already showing, `in` doesn't play In again. It just takes the new data, exactly as `update` would, and a change to one of its trigger fields plays Change.

## out

Takes things off air, playing their Out. By default it acts on one component; `scope` widens it to a layer or everything.

- `scope` ("component" | "layer" | "root"): Defaults to `"component"`.
- `component` (string): With the component scope: the component's id.
- `layer` (string): With `scope: "layer"`: the layer's id. Every component on it goes off air.

```json
{ "command": "out", "component": "lower-third" }
{ "command": "out", "scope": "layer", "layer": "sponsors" }
{ "command": "out", "scope": "root" }
```

`scope: "root"` clears the output: everything goes off air. What comes off air keeps its data.

## update

Merges values into data without changing what's on air. On a component that's showing, a change to one of its trigger fields plays its Change.

- `scope` ("component" | "layer" | "root"): Defaults to `"component"`. `"layer"` updates a layer's data and `"root"` the composition's global data, which fields inherit from.
- `component` (string): With the component scope: the component's id.
- `layer` (string): With `scope: "layer"`: the layer's id.
- `data` (object, required): Values by field key: strings, numbers, booleans, or `null` to clear.

```json
{ "command": "update", "scope": "root", "data": { "homeScore": 3, "awayScore": 1 } }
```

## invoke

Plays one of a component's events, such as a custom `Goal` event.

- `component` (string, required): The component's id.
- `event` (string, required): The event's id.

```json
{ "command": "invoke", "component": "score-bug", "event": "goal" }
```

## timer

Starts, pauses, resets or sets a countdown or count-up field. Clocks and countdowns to a time follow the wall clock, so they can't be started or stopped.

- `timer` (string, required): The timer field's id.
- `action` ("start" | "pause" | "reset" | "set", required): `reset` goes back to the timer's starting time. `set` moves it to the time you give.
- `ms` (number): For `set`: the time in milliseconds.
- `time` (string): For `set`: the time as text instead, such as `"5:00"`.

```json
{ "command": "timer", "timer": "clock", "action": "set", "time": "45:00" }
{ "command": "timer", "timer": "clock", "action": "start" }
```

The output runs every timer on its own clock, so every renderer shows the same time. A countdown can fire an event on a component when it reaches zero; set that up on the timer field in the editor.