> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asccli.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow

# workflow

> Run multi-step automation workflows with `workflow.json`

Define named, multi-step automation sequences in `.asc/workflow.json`. Each workflow composes existing `asc` commands and shell commands, keeps stdout machine-parseable JSON, and supports reusable sub-workflows.

## Quick start

```bash theme={null} theme={null}
asc workflow list
asc workflow validate
asc workflow run beta
```

## Workflow file format

Workflows are defined in `.asc/workflow.json`:

```json theme={null} theme={null}
{
  "env": {
    "APP_ID": "123456789",
    "VERSION": "1.0.0",
    "IPA_PATH": "./build/MyApp.ipa"
  },
  "before_all": "asc auth status",
  "after_all": "echo workflow_done",
  "error": "echo workflow_failed",
  "workflows": {
    "beta": {
      "description": "Distribute a build to a TestFlight group",
      "env": {
        "GROUP_ID": ""
      },
      "steps": [
        {
          "name": "resolve_build",
          "run": "asc builds info --app $APP_ID --latest --platform IOS --output json",
          "outputs": {
            "BUILD_ID": "$.data.id"
          }
        },
        {
          "name": "add_build_to_group",
          "run": "asc builds add-groups --build-id ${steps.resolve_build.BUILD_ID} --group $GROUP_ID"
        }
      ]
    },
    "release": {
      "description": "Run the full App Store release pipeline",
      "steps": [
        {
          "workflow": "preflight",
          "with": {
            "NOTE": "running private sub-workflow"
          }
        },
        {
          "name": "release",
          "run": "asc publish appstore --app $APP_ID --ipa $IPA_PATH --version $VERSION --submit --confirm"
        }
      ]
    },
    "preflight": {
      "private": true,
      "description": "Private helper workflow",
      "steps": [
        {
          "name": "preflight",
          "run": "echo \"$NOTE\""
        }
      ]
    }
  }
}
```

## Commands

### workflow list

List public workflows from `workflow.json`:

```bash theme={null} theme={null}
asc workflow list
asc workflow list --all
asc workflow list --file ./custom-workflows.json
```

### workflow validate

Validate structure, references, cycles, and output declarations:

```bash theme={null} theme={null}
asc workflow validate
asc workflow validate --file ./.asc/workflow.json
```

### workflow run

Run a workflow by name and pass runtime parameters as `KEY:VALUE` arguments:

```bash theme={null} theme={null}
asc workflow run beta
asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef
asc workflow run release VERSION:2.1.0
asc workflow run --dry-run beta
asc workflow run --resume beta-20260312T120000Z-deadbeef release
```

## Features

### Hooks

Use `before_all`, `after_all`, and `error` hooks for common setup, cleanup, or failure handling.

### Sub-workflows

Steps can reference another workflow with a `workflow` key and pass scoped variables through `with`.

### Persistent outputs

If a step emits JSON and declares `outputs`, later steps can reference values like `${steps.resolve_build.BUILD_ID}`.

### Repo-local run state

Workflow runs persist state next to the workflow file so you can resume interrupted runs with `--resume`.

## Output

All workflow commands emit JSON to stdout. Step and hook output streams to stderr so stdout stays machine-parseable.

## Security notes

<Warning>
  Workflows intentionally execute arbitrary shell commands. Only run workflow files you trust, especially when using `--file`.
</Warning>

* Treat `.asc/workflow.json` like code and review it before running
* `asc workflow validate` checks structure and wiring, not shell-command safety
* Steps inherit your process environment, so be careful with secrets
* Declared outputs are persisted in run-state files; avoid mapping secrets into outputs

## Related

<CardGroup cols={2}>
  <Card title="Workflow configuration" icon="file-json" href="/configuration/workflows">
    Learn the workflow file structure and patterns
  </Card>

  <Card title="Automation guide" icon="robot" href="/guides/automation">
    See release automation examples and production patterns
  </Card>
</CardGroup>