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

# Run a plan

> Run a plan with input and pipe its output to jq.

`changes_since` takes a git ref as its `base` input and returns the commits merged since it.

```yaml .graph/plans/changes_since.yaml theme={null}
version: 2
identifier: changes_since
name: Changes since
description: The commits merged since a git ref.
input_schema:
  type: object
  required:
  - base
  properties:
    base:
      type: string
      description: The ref to start after, such as a release tag
steps:
- id: commits
  tool_name: github__tool__git_log
  input:
    base: '{{input.base}}'
    head: HEAD
finish:
  output:
    count: '{{commits.count}}'
    commits: '{{commits.commits}}'
```

## See what it needs

Run `changes_since` without inputs:

```bash theme={null}
graph plan run changes_since
```

graph checks the inputs before any step runs. It names what's missing, prints the input schema, and exits with code 3:

```text theme={null}
plan 'changes_since' needs inputs:
  - "base" is a required property
input schema:
{
  "properties": {
    "base": {
      "description": "The ref to start after, such as a release tag",
      "type": "string"
    }
  },
  …
}
```

## Pass the input

Set `base` with `--input`:

```bash theme={null}
graph plan run changes_since \
  --input base=v0.15.0
```

The plan prints its result as JSON on stdout:

```json theme={null}
{
  "commits": [
    {
      "author": "Tyler Davis",
      "date": "2026-10-08T19:39:09-06:00",
      "pr": null,
      "sha": "648d34e22ede0d8c246576493b39487237272607",
      "short_sha": "648d34e",
      "subject": "feat!: plans state how they finish with a required finish key…"
    },
    …
  ],
  "count": 28
}
```

## Pipe the result into jq

Progress goes to stderr, so stdout carries only the result and pipes cleanly:

```bash theme={null}
graph plan run changes_since \
  --input base=v0.15.0 \
  | jq -r '.commits[] | "\(.short_sha) \(.subject)"'
```

```text theme={null}
648d34e feat!: plans state how they finish with a required finish key…
cd01c05 feat!: workbench agents work on plans through the same artifact tools…
1a8443c ci: a planner eval harness with goal sets, reference plans and a judge…
…
```

## Related guides

> **[Handle failures](/plans/guides/handle-failures)**
>
> Tell why a run failed and choose how to respond.

> **[Debug a plan](/plans/guides/debug-a-plan)**
>
> Step through a run in the workbench.

> **[Draft a plan in the workbench](/plans/guides/draft-in-workbench)**
>
> Turn a goal into a working, saved plan.


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