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

# Run a workflow

> Start a workflow from Automations or with pinework workflow start, then watch each step's run and state.

A **workflow** is a program of steps that Pinework runs for you. Each step dispatches one run. An agent step gives an agent a prompt. A gate step runs a command in an agent's checkout and passes or fails on its exit code. The program waits for a step's result before it uses it.

Pinework ships built-in workflows, such as **Single agent step** and **Build a slice**. Your agents can also write workflows for your workspace. The dashboard lists both on the **Automations** page, under **Workflows**.

## Before you start

* You have an agent in your workspace. See [Create an agent](/guides/create-an-agent).
* For the CLI tab, you have signed in with `pinework login`.

## Start a workflow and watch its steps

<Steps>
  <Step title="Pick a workflow">
    <Tabs>
      <Tab title="Dashboard">
        Open **Automations** in the sidebar. The **Workflows** section lists each workflow with its description and its last run. Click a name to read its program under **Code**.
      </Tab>

      <Tab title="CLI">
        List the built-in workflows and the inputs each one needs:

        ```bash theme={null}
        pinework workflow catalog
        ```

        List the workflows in your workspace, including ones your agents wrote:

        ```bash theme={null}
        pinework workflow list
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Start it">
    This example starts **Single agent step**. It runs one agent on one prompt.

    <Tabs>
      <Tab title="Dashboard">
        1. In the **Workflows** section, click **Start** next to the workflow.
        2. Set **Access**. **Check first** asks you before any action without a rule runs. **Full access** runs it, and your ask and deny rules still apply.
        3. Fill in the inputs. For **Single agent step**, pick the **Agent** and write the **Prompt**.
        4. Click the start button. It reads `Start` plus the workflow's title.

        The start button stays disabled and names the missing field until every required input is filled.
      </Tab>

      <Tab title="CLI">
        ```bash theme={null}
        pinework workflow start single_agent_step \
          --input agentId=agt_… \
          --input prompt="Summarize the open pull requests in one list." \
          --mode ask
        ```

        Pass each input as `--input key=value`. The CLI checks required inputs before it starts the run. `--mode` is `ask` (check first) or `full` (full access). Leave it out to use the workflow's default. Add `--task tsk_…` to tie the run to a task.
      </Tab>
    </Tabs>

    When it works, the dashboard shows a toast that the workflow started. The CLI prints the workflow run as JSON. Its `id` starts with `flr_` and its `status` is `running`.

    Some workflows, such as **Build a slice**, run only with full access. Their **Access** field is fixed. A CLI start with `--mode ask` still prints a run. That run then fails at once. Its summary says the engine refused the start.
  </Step>

  <Step title="Watch each step">
    <Tabs>
      <Tab title="Dashboard">
        Open **Automations**, click the **Runs** tab, and click the workflow run.

        The **Steps** table has one row per step. It shows the step's number, its kind (**Agent** or **Gate**), its state, the run it dispatched and the agent. A gate row also shows the command and its exit code. The page refreshes every 15 seconds while the workflow runs.
      </Tab>

      <Tab title="CLI">
        ```bash theme={null}
        pinework workflow runs get flr_…
        ```

        The output has a `steps` array. Each step has its `state`, the `run` it dispatched with that run's status, and the agent. To list runs by status:

        ```bash theme={null}
        pinework workflow runs list --status running
        ```
      </Tab>
    </Tabs>

    A step moves through these states:

    | State | Meaning |
    | - | - |
    | Dispatched | The step's run started. The program waits on it. |
    | Waiting | The run finished. Pinework has not sent its result to the program yet. |
    | Resumed | Pinework sent the result. The program has not moved on yet. |
    | Done | The program took the result and moved on. |

    Click a step's run to read its run trace. When the workflow ends, its status reads **Ran** or **Failed**.
  </Step>

  <Step title="Answer when a step needs you">
    A workflow can stop and wait for you in two ways.

    * **An approval.** With **Check first**, an action without a rule waits for your approval. The step's state reads **Waiting on you** and links to the approval. See [Answer approvals](/guides/answer-approvals).
    * **A question.** Some workflows ask you what to do next, such as after a failed gate. A card marked **Needs you** shows the question and its answers. It appears on the workflow run's page and at the top of the **Runs** tab.

    Click an answer on the card. When it works, a toast says the workflow is resuming.
  </Step>
</Steps>

## Start a workflow an agent wrote

An agent writes a workflow as a JavaScript program. It declares a `meta` object, then calls agent steps through `pw`. A short one looks like this:

```js theme={null}
export const meta = {
  name: "draft_and_check",
  title: "Draft and check",
  inputs: [{ key: "topic", label: "Topic", required: true }],
};

const draft = await pw.agent(`Write a short release note about ${pw.input.topic}.`, { label: "Draft" });
if (!draft.ok) throw new Error("The draft step failed");

await pw.agent(`Check this release note for errors:\n\n${draft.summary}`, { label: "Check" });
```

The agent saves it with `pinework workflow create --file <program.js>`. Start it from the CLI by its `meta.name`:

```bash theme={null}
pinework workflow get draft_and_check
pinework workflow start draft_and_check --input topic="the new billing page"
```

Its steps run as the agent that wrote it, unless a step names another agent. The dashboard shows its code and runs. The dashboard's **Start** button appears only on built-in workflows.

## Fix a workflow that does not start or move

<Accordion title="The CLI says required inputs are missing">
  Every required input needs a value. Run `pinework workflow catalog` or `pinework workflow get <name>` to see each input's key. Then pass it as `--input key=value`.
</Accordion>

<Accordion title="A workflow you created yourself fails at once">
  A workflow you wrote needs an agent for its steps to run as. A workflow created from your own login has no author agent. Started by you, it fails with a message that nobody can run it. Ask an agent to write and save the workflow instead.
</Accordion>

<Accordion title="The start is refused because the workflow was retired">
  `pinework workflow delete <name>` retires a workflow. A retired workflow cannot start. Its past runs still show, and runs already going still finish.
</Accordion>

<CardGroup cols={2}>
  <Card title="Answer approvals" href="/guides/answer-approvals">
    Approve or deny what a workflow step waits on.
  </Card>

  <Card title="Runs" href="/concepts/runs">
    Read the run each step dispatched.
  </Card>

  <Card title="Schedule a routine" href="/guides/schedule-a-routine">
    Give one agent a prompt on a schedule.
  </Card>

  <Card title="Approvals and questions" href="/concepts/approvals-and-questions">
    How Pinework pauses work for your answer.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.