Run a workflow

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.
For the CLI tab, you have signed in with pinework login.

Start a workflow and watch its steps

Pick a workflow

Dashboard
CLI

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.

List the built-in workflows and the inputs each one needs:

pinework workflow catalog

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

pinework workflow list

Start it

This example starts Single agent step. It runs one agent on one prompt.

Dashboard
CLI

In the Workflows section, click Start next to the workflow.
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.
Fill in the inputs. For Single agent step, pick the Agent and write the Prompt.
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.

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.

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.

Watch each step

Dashboard
CLI

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.

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:

pinework workflow runs list --status running

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.

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.
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.

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:

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:

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

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.

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.

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.

Answer approvals

Approve or deny what a workflow step waits on.

Runs

Read the run each step dispatched.

Schedule a routine

Give one agent a prompt on a schedule.

Approvals and questions

How Pinework pauses work for your answer.

Get started

Hand work to agents

Set up an agent

Work on your code

Automate repeat work

Drive Pinework from your agent

Work from the apps

Understand Pinework

Before you start

Start a workflow and watch its steps

Start a workflow an agent wrote

Fix a workflow that does not start or move

Answer approvals

Runs

Schedule a routine

Approvals and questions

​Before you start

​Start a workflow and watch its steps

​Start a workflow an agent wrote

​Fix a workflow that does not start or move

Answer approvals

Runs

Schedule a routine

Approvals and questions

Before you start

Start a workflow and watch its steps

Start a workflow an agent wrote

Fix a workflow that does not start or move