Drop a GitHub, AWS, Google Cloud, Jira, or Maven action into a workflow as easily as a built-in step. User tools appear in the Builder library by name, check their inputs against a schema, return typed JSON that later steps can use, and pin the exact revision you selected. The workflow you reviewed is the workflow that runs.

This page covers using a tool that is already installed. To write your own, see Build User Tools.

Every installed tool gets its own named entry in the Builder library.

Get the starter pack

The valdr-tools starter pack is the fastest way to see user tools in action. It ships:

Tools	What they do	Needs on the workflow host
Node, TypeScript, Python, Shell, and Native text summary	The same harmless `summarize` action in five languages, ready to copy	Node, Bun, Python 3, `sh` and `jq`, or a compiled binary
GitHub CLI, AWS CLI, Google Cloud CLI, Atlassian CLI	Selected read actions such as `pr-list`, `s3-list-buckets`, `run-services-list`, and `jira-workitem-view`	Node, plus that CLI, installed and signed in
Maven	Run build goals and return a pass or fail result with an error excerpt instead of the full log	Node and a JDK, plus Maven unless the project has `mvnw`

The CLI adapters are starters, not complete CLI wrappers. They cover useful read actions. Add the commands and flags your workflows need by extending a starter.

To install it:

Build the valdr-tools archive from its source in the valdr-packs repository.
Open Settings > Valdr Packs > Import Pack, select the archive, review the preview, and import.
Open Workflows > Tools to confirm the tools are installed and inspect any tool’s details, including its manifest and source location. See the Tools tab.

Imported tools are available in the Builder immediately.

Run the summary action

Start with Node text summary (valdr-tools.user.node). It counts text locally, with no network access and no repository changes, so it is a safe first run.

In the Builder, click or drag Node text summary from the User tools library group. Its single action, summarize, is selected automatically. For a tool with several actions, choose one in the inspector’s Action field.
In the inspector’s Inputs section, choose the text input and enter the text to count.
Map the outputs you want later steps to use.
Choose Test, then open the run in Runs to see the result.

The inspector shows exactly which installed revision and content hash the step will run.

In YAML, the same step’s inputs and output mappings look like this:

inputs:
  text: "Hello Valdr\nTools are ready."
outputs:
  characters: "$.normalized.data.characters"
  words: "$.normalized.data.words"
  lines: "$.normalized.data.lines"

The successful result is:

{"characters":28,"words":5,"lines":2}

A later step can use ${steps.summarize.outputs.words} when this step’s key is summarize and the later step declares needs: [summarize].

Simple inputs appear as named fields. Tools with nested or list inputs take a JSON object instead. Either way, Valdr checks the input against the action’s schema before the program starts.

Pinned to the revision you reviewed

When you add a tool, the step records the tool’s exact revision, content hash, and input and output schemas. Importing a newer revision later never changes existing steps or past runs. The Builder offers the newest revision for new steps. To upgrade an existing step, select the newer revision in Installed revision and save a new workflow version.

The full saved reference is described in Pin a user tool.

Host access and limits

User tools run on the workflow host with your user’s permissions, just like Command steps. The working directory is a starting point, not a sandbox. Review a tool’s code and declared side effects before running a workflow that uses it.

Import never runs anything. Previewing or importing a pack doesn’t execute tool code, install dependencies, or sign in to a CLI. The program runs only when a workflow step executes, using the runtimes, CLIs, and credentials already on the workflow host. The pinned source doesn’t pin the version of an external CLI or runtime; those stay under your control.

Working directory. By default a tool runs in the worktree of the agent session that started the workflow. A run without a session uses the project’s repository, and a run with neither uses the folder Valdr was started from. Set Working directory (cwd) on the step to override it. Absolute paths are used as-is; relative paths resolve from that default. In YAML, cwd sits beside tool and inputs, and expressions work:

cwd: "${workflow.inputs.workingDirectory}"
inputs:
  text: "Hello Valdr\nTools are ready."

Environment and credentials. Tools receive a small baseline environment (PATH, HOME, TMPDIR, LANG, and LC_*) plus the variables the tool’s manifest requests by name. Keep credentials in the host environment or in the CLI’s own sign-in. Don’t put secrets in workflow inputs, which are saved in run history.

Limits. A tool’s manifest can set stricter limits, but never beyond these:

Limit	Maximum
Run time	300 seconds
Request size	1 MiB
Result size	1 MiB
Saved stderr	1 MiB

Oversized requests fail before the program starts. On a timeout or oversized result, Valdr attempts to stop the program. Stderr over the limit is not retained.

Redaction is best effort. It may miss sensitive values in errors or logs, and successful result data is not redacted by Valdr. Tool authors are responsible for what their tools return and log. Review a tool’s output before using or sharing it; see Redaction and sensitive output.

Retries, cancellation, and recovery

Retry step sends the step’s original input with the same operationId and a new attemptId, so a well-built tool can recognize a repeat.
Uncertain outcomes stop the line. If an action declared as manual-retry or unknown-effect fails after it starts, or Valdr stops mid-attempt and can’t confirm the outcome, the step is blocked with a needs attention failure and Retry step isn’t offered. Check the external system and reconcile what happened, then cancel the run, and start a new one if the work still needs to happen.
Cancel run attempts to stop the tool. It can’t undo writes the tool already made, and detached or external work may continue.

See Reliability and Recovery for the details.

Remove a revision

In Workflows > Tools, open the revision’s card and choose Remove from catalog. Use Show all versions to reach older revisions. Removal hides that revision from new steps; existing workflows that pin it keep working, and run history is preserved.

Maven builds

Add Maven and choose the build action. In Inputs JSON object, set the goals you need, such as {"goals": ["clean", "verify"]} (the default is ["package"]). If your pom.xml isn’t at the root of the step’s working directory, set Working directory (cwd) too. A failing build doesn’t fail the step: the tool returns result: failed, a one-line summary, and an error excerpt, and keeps the build log on the workflow host. The starter’s redaction is best effort; review the output before sharing it or sending it to an agent. Route a failed build back to the agent that made the change, or anywhere else your process needs. See Maven Builds.

Next step

Continue with Session Steps to add agent work. To write your own local action, follow Build Your First Tool. If a tool is missing or failing, see workflow troubleshooting.

Command Session Steps