Build User Tools
{"content":"{{\u003c tier level=\"sovereign\" note=\"User Tools extend Valdr Workflows with your own programs and CLI adapters.\" \u003e}}\n\nEvery 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.\n\nWrite your tool in any language that can read standard input and write standard output. No SDK, plugin API, or MCP server is required.\n\n{{\u003c 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.\" \u003e}}\n\n## Why not just run a command?\n\nA [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.\n\n{{\u003c process-compare\n leftTitle=\"Script in a shell command\"\n leftSteps=\"Free-form string|Unchecked arguments|Text output to parse|Script can change underneath|Retry and hope\"\n leftTone=\"human\"\n rightTitle=\"User tool\"\n rightSteps=\"Named action|Schema-checked inputs|Typed JSON outputs|Pinned revision and hash|Declared retry behavior\"\n rightTone=\"workflow\"\n 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.\"\n\u003e}}\n\nThe 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.\n\n## How it works\n\n{{\u003c process-flow\n steps=\"Write the program|Describe actions|Package the pack|Import|Add to a workflow|Run and map results\"\n phaseTitles=\"Build once|Reuse in every workflow\"\n highlight=\"Add to a workflow\"\n 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.\"\n\u003e}}\n\nYou create three things:\n\n- **A program** that reads one JSON request and writes one JSON result.\n- **A manifest** (`.tool.yaml`) that names the tool, its actions, and the inputs and outputs of each action.\n- **A pack** that bundles those files so you can import them into Valdr, or share them with your team.\n\nAfter import, the tool appears in **Workflows \u003e Tools** and in the Builder's **User tools** library group.\n\n{{\u003c callout type=\"info\" \u003e}}\n**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.\n{{\u003c /callout \u003e}}\n\n## Find what you need\n\nStart 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.\n\n| I want to… | Read |\n| --- | --- |\n| Start from working code or a ready-made CLI adapter | [Use the Starter Pack](starters/) |\n| Use a tool someone already built | [User Tools](/valdr/docs/workflows/steps/user-tool/) |\n| Build a tool from scratch | [Build Your First Tool](quickstart/) |\n| Import a tool or ship a new version | [Package, Import, and Update](package-and-run/) |\n| Turn an installed CLI into workflow actions | [Wrap a CLI](cli-adapters/) |\n| Run Java builds without flooding the run with logs | [Maven Builds](maven/) |\n| Look up a manifest field or schema rule | [Manifest and Schemas](manifest/) |\n| Understand requests, results, and retries | [Requests and Execution](runtime/) |\n| Diagnose a tool that fails | [Test and Troubleshoot](testing/) |\n\n## Next step\n\n[Use the Starter Pack](starters/) to explore working examples and choose a starting point for your own tool.","description":"Turn the scripts and CLIs you already trust into typed, version-pinned workflow steps.","title":"Build User Tools"}
Sovereign
Sovereign tier required. 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.
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 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.
Script in a shell command
Free-form string
Unchecked arguments
Text output to parse
Script can change underneath
Retry and hope
User tool
Named action
Schema-checked inputs
Typed JSON outputs
Pinned revision and hash
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
Build once
Write the program
Describe actions
Package the pack
Reuse in every workflow
Import
Add to a workflow
Run and map 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.
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.
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 |
| Use a tool someone already built | User Tools |
| Build a tool from scratch | Build Your First Tool |
| Import a tool or ship a new version | Package, Import, and Update |
| Turn an installed CLI into workflow actions | Wrap a CLI |
| Run Java builds without flooding the run with logs | Maven Builds |
| Look up a manifest field or schema rule | Manifest and Schemas |
| Understand requests, results, and retries | Requests and Execution |
| Diagnose a tool that fails | Test and Troubleshoot |
Next step
Use the Starter Pack to explore working examples and choose a starting point for your own tool.