# Build User Tools
{{< tier level="sovereign" note="User Tools extend Valdr Workflows with your own programs and CLI adapters." >}}

Every team has scripts that matter: the build wrapper, the release check, the one-liner that reads a ticket or a cloud account. User Tools turn those programs into first-class workflow steps. Describe each action once in a short YAML manifest, and Valdr gives it a named entry in the Builder, schema-checked inputs, typed JSON outputs for later steps, and a pinned revision, so a workflow keeps running the exact code you reviewed.

Write your tool in any language that can read standard input and write standard output. No SDK, plugin API, or MCP server is required.

{{< thumbcard src="/images/ui/workflows/builder-user-tool-step.png" alt="Workflow Builder with the User tools library group, a Node text summary step on the canvas, and the inspector showing its tool ID, action, and pinned installed revision" caption="Installed tools appear in the Builder by name. Each step pins the exact revision and content hash you selected." >}}

## Why not just run a command?

A [Command step](/valdr/docs/workflows/steps/command/) is ideal for a one-off `npm test`. Once a script becomes something several workflows depend on, a loose shell string starts to cost you: inputs go unchecked, output is text you have to parse, and the script can change underneath a workflow you already reviewed.

{{< process-compare
  leftTitle="Script in a shell command"
  leftSteps="Free-form string|Unchecked arguments|Text output to parse|Script can change underneath|Retry and hope"
  leftTone="human"
  rightTitle="User tool"
  rightSteps="Named action|Schema-checked inputs|Typed JSON outputs|Pinned revision and hash|Declared retry behavior"
  rightTone="workflow"
  aria="A script in a shell command goes from a free-form string to unchecked arguments, text output to parse, a script that can change underneath, and retry and hope. A user tool goes from a named action to schema-checked inputs, typed JSON outputs, a pinned revision and hash, and declared retry behavior."
>}}

The payoff compounds. Write the adapter once, and every workflow that needs it gets the same validated contract, the same reviewed code, and a step result you can inspect after every run.

## How it works

{{< process-flow
  steps="Write the program|Describe actions|Package the pack|Import|Add to a workflow|Run and map results"
  phaseTitles="Build once|Reuse in every workflow"
  highlight="Add to a workflow"
  aria="Build once: write the program, describe its actions, and package the pack. Reuse in every workflow: import it, add it to a workflow, then run it and map its results."
>}}

You create three things:

- **A program** that reads one JSON request and writes one JSON result.
- **A manifest** (`.tool.yaml`) that names the tool, its actions, and the inputs and outputs of each action.
- **A pack** that bundles those files so you can import them into Valdr, or share them with your team.

After import, the tool appears in **Workflows > Tools** and in the Builder's **User tools** library group.

{{< callout type="info" >}}
**Local-first:** User tools run on the machine running Valdr (the *workflow host*), as your user, with the runtimes and CLI sign-ins already installed there. Valdr keeps the reviewed tool source and every run's evidence in your local workspace until you delete them.
{{< /callout >}}

## Find what you need

Start with the starter pack to see what's available, then build and run your own tool. The CLI and Maven guides show how to apply the same pattern to your projects. Keep the schema and execution references nearby as you build, and use the troubleshooting guide when something fails.

| I want to… | Read |
| --- | --- |
| Start from working code or a ready-made CLI adapter | [Use the Starter Pack](starters/) |
| Use a tool someone already built | [User Tools](/valdr/docs/workflows/steps/user-tool/) |
| Build a tool from scratch | [Build Your First Tool](quickstart/) |
| Import a tool or ship a new version | [Package, Import, and Update](package-and-run/) |
| Turn an installed CLI into workflow actions | [Wrap a CLI](cli-adapters/) |
| Run Java builds without flooding the run with logs | [Maven Builds](maven/) |
| Look up a manifest field or schema rule | [Manifest and Schemas](manifest/) |
| Understand requests, results, and retries | [Requests and Execution](runtime/) |
| Diagnose a tool that fails | [Test and Troubleshoot](testing/) |

## Next step

[Use the Starter Pack](starters/) to explore working examples and choose a starting point for your own tool.