---
title: 'Add your first workflow'
description: 'Add a job that runs in steps, start it, and watch it finish in the dashboard.'
position: 5
---

# Add your first workflow

> A workflow is a job you split into **steps**. Stackbone runs each step once and
> saves its result. If the process dies halfway through and comes back, the
> workflow resumes at the first unfinished step, which is what makes it
> **durable**.

> Use a workflow for work that takes a while or must not run twice by accident: a
> batch import, a nightly report. You start it with an input and get a result back
> when the last step finishes.

## Add one to your workspace

Add a workflow to the workspace you already have:

```sh
stackbone add workflow hello
```

The command writes one new file, `workflows/hello.workflow.ts`, and changes
nothing else. If `stackbone dev` is running, it picks up the new file. If not,
start it from the workspace folder.

## See it in the dashboard

In **Studio** (the dashboard `stackbone dev` prints a link to), open **Catalog**
from the left menu. Your workflow appears next to the agent you already had.
Click it to see its steps and the input it expects:

![The Catalog in Studio, showing the new workflow next to the agent.](/images/first-steps/studio-workflows.png)
_Studio reads this list from your running workspace._

## Run it

Start it from **Playground**, also in the left menu: pick your workflow in the
target picker at the top, fill in the example input, and click **Run**.

Or start it from the terminal by name. Stackbone checks your input against the
shape the workflow expects. The starter one takes a single text field called
`message`:

```sh
stackbone workflows start hello --input '{"message": "hello"}'
```

Either way, you get back a **run**: one execution of the workflow you can follow.

## Watch it finish

Open **Runs** in the left menu and click your run. You see each step in order,
how long it took, and the input and output at every stage:

![A finished workflow run in Studio, showing its steps one after another with timings.](/images/first-steps/workflow-run.png)
_A finished run, step by step._

Follow the same run from the terminal:

```sh
stackbone runs list
stackbone runs get <runId>
```

You now have a working workflow. Edit the steps in
`workflows/hello.workflow.ts` and start it again. The next run shows your own
steps in Runs.

## What's next

- **[Use Stackbone with coding agents](/docs/home/get-started/coding-agents)**:
  the skills that teach your coding agent the Stackbone CLI and SDK.