# agility workflows

> Source: https://agilitycms.com/docs/developers/cli-workflows

`agility workflows` (alias `agility workflow`) runs a workflow operation (publish, unpublish, approve, decline or request approval) on content items and pages in the **target** of an earlier sync. It finds the items through that sync's mapping files, or you can name target IDs directly.

Checked against `@agility/cli` 1.1.0. For the options every command shares, sign-in and exit codes, see the [CLI command reference](/docs/developers/cli-reference).

## Usage

```bash
agility workflows --sourceGuid=<source> --targetGuid=<target> --locales=<locale> --operationType=<operation> [options]
```

From `agility workflows --help`:

```text
agility workflows

Perform workflow operations (publish, unpublish, approve, decline,
requestApproval) on content and pages from existing mappings.
```

## Choosing the operation: --operationType

> [!WARNING]
> `--operationType` doesn't appear in `--help` in 1.1.0, but the command reads it. **If you leave it out, the command publishes.** A value it doesn't recognize also publishes. Always pass it, and check the `WORKFLOW OPERATION:` line at the start of the output.

| Value | Also accepted | What it does on the target |
| --- | --- | --- |
| `publish` | `pub` | Publishes. Only items that are **published in the source** are published; staging-only items are skipped |
| `unpublish` | `unpub` | Unpublishes every matched item |
| `approve` | `app` | Approves every matched item |
| `decline` | `dec` | Declines every matched item |
| `requestApproval` | `request-approval`, `request_approval`, `req` | Requests approval for every matched item |

Other spellings of the option: `--operation-type`, `--OperationType`, `--OPERATION_TYPE`, `--op` and `--type`. Values are not case-sensitive.

## Options

| Option | Default | What it does |
| --- | --- | --- |
| `--sourceGuid` | from `.env` | The source of the earlier sync. Used to find the mapping files and to check what is published in the source |
| `--targetGuid` | from `.env` | The instance the operation runs on |
| `--locales` | | The locale to work in. The operation runs in the **first** locale you list, so run the command once per locale. Always pass it |
| `--operationType` | `publish` | See above |
| `--contentIDs` | none | Comma-separated **target** content IDs. Skips the mapping lookup, for example `--contentIDs=121,1221,345` |
| `--pageIDs` | none | Comma-separated **target** page IDs. Skips the mapping lookup, for example `--pageIDs=12,11,45` |
| `--list` | `false` | Lists the source and target pairs that have mapping files in `agility-files/mappings/`, with their locales and item counts, then exits. Doesn't sign in or change anything |
| `--token`, `--headless`, `--verbose` | | As for every command. See the [command reference](/docs/developers/cli-reference#options-shared-by-every-command) |

`--contentIDs` and `--pageIDs` are only read by `workflows`. Earlier documentation listed them under sync; sync ignores them.

The other shared options in `--help` (`--elements`, `--models`, `--pages`, `--preflight` and so on) don't affect this command.

## What it acts on

- **From mappings (default):** every content item and page recorded in `agility-files/mappings/{sourceGuid}-{targetGuid}/` for the locale. Run it from the folder that holds those files. If there are none, it prints `No mappings found to process.` and stops.
- **From IDs:** with `--contentIDs` or `--pageIDs`, only those target items. For `publish`, the CLI still uses the mappings to check which of them are published in the source, and skips the rest.

Items are processed in batches through Agility's batch workflow API. After a publish, the mapping files are updated with the newly published versions.

## Examples

```bash
# Which source/target pairs have mappings here?
agility workflows --list

# Publish everything that is published in the source (en-us)
agility workflows --sourceGuid="A-u" --targetGuid="B-u" --locales="en-us" --operationType="publish"

# Same for a second locale: one run per locale
agility workflows --sourceGuid="A-u" --targetGuid="B-u" --locales="fr-ca" --operationType="publish"

# Request approval for two specific target items
agility workflows --sourceGuid="A-u" --targetGuid="B-u" --locales="en-us" \
  --operationType="requestApproval" --contentIDs="121,1221"

# Unpublish two target pages
agility workflows --sourceGuid="A-u" --targetGuid="B-u" --locales="en-us" \
  --operationType="unpublish" --pageIDs="12,45"
```

If you only want to publish what you just synced, `agility sync --autoPublish` does it in the same run. See [sync and push](/docs/developers/cli-sync).

## Exit behavior

- Exits `1` when any item fails, and `0` when the operation finishes without failures (including when there was nothing to process).
- `--list` exits `0`.
- In 1.1.0, if sign-in fails or a required setting is missing, the command stops without setting a failing exit code. In CI, check the output for the `COMPLETE` summary.

## Related

- [sync and push](/docs/developers/cli-sync)
- [CLI CI/CD Integration Guide](/docs/developers/cli-ci-cd-integration-guide): a sync-then-publish pipeline