# Commands & Workflows (/docs/layers/commands)



A **command** is a verb on a layer — `refresh-schedule`, `process-due`,
`disable-underperforming`, etc. Commands map to versioned workflows.

## Triggering a command [#triggering-a-command]

### From the UI [#from-the-ui]

Open the layer detail page → **Commands** tab → click **Run** on any row.
A dialog asks for parameters (if the workflow needs any). Confirm and the
workflow is queued.

### From the CLI [#from-the-cli]

The `layers` CLI can authenticate and invoke commands via the Partner API —
see [CLI install](/docs/cli/install).

### From the Partner API [#from-the-partner-api]

```bash
curl -X POST https://api.layers.com/api/project-layers/{projectLayerId}/execute \
  -H "Authorization: Bearer $LAYERS_TOKEN" \
  -d '{ "commandId": "refresh-schedule", "parameters": {} }'
```

The `initialize` command is handled internally during layer install and is
not externally callable.

## Common commands [#common-commands]

Examples from the Social Distribution template:

| Command                      | Trigger                    | What it does                                    |
| ---------------------------- | -------------------------- | ----------------------------------------------- |
| `initialize`                 | once on install (internal) | Sets up resources, validates config.            |
| `refresh-schedule`           | executable                 | Recompute upcoming distribution slots.          |
| `refresh-schedule-scheduled` | scheduled (nightly)        | Same, but auto.                                 |
| `attach-to-schedule`         | executable                 | Atomically claim a slot for a generated post.   |
| `process-due`                | scheduled (every minute)   | Publish posts whose scheduled time has arrived. |

Examples from Meta / TikTok Ad Manager:

| Command                | Trigger                  | What it does                                                      |
| ---------------------- | ------------------------ | ----------------------------------------------------------------- |
| `content-refresh`      | scheduled (every 15 min) | Disable underperformers + add fresh eligible creatives to adsets. |
| `ad-optimize`          | scheduled (every 6h)     | Optimizer pipeline — propose pauses / budget moves / bid moves.   |
| `ad-optimize-watchdog` | scheduled (every 2h)     | Catch catastrophic spend with 0 installs.                         |

## Scheduled commands [#scheduled-commands]

Commands ending in `-scheduled` run on a cron managed by the
[scheduler](/docs/concepts/scheduler). Override the cron in the layer
[config](/docs/layers/config).

## Watching a workflow [#watching-a-workflow]

After triggering, the workflow appears in the **Runs** tab with status
`running`. Click it to see:

* Activities executed in order.
* Inputs / outputs of each activity.
* Logs streamed live.
* Heartbeat indicators (for long activities).

## Failure & retry [#failure--retry]

Failed workflows are visible in the runs tab with a stack trace. Most
activities are idempotent and retry-safe; you can click **Retry** to
re-run.

## Cross-layer execution [#cross-layer-execution]

Some workflows operate across multiple layers or projects in the same Org.
Filters: `projectId`, `templateIds`, `statusFilter`, `whereContains` (JSON
contains on `config`). This is how Org-wide refresh cycles work.