# User Tools
{{< tier level="sovereign" note="User tools let workflows reuse your own programs through portable action contracts." >}}

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](/valdr/docs/workflows/user-tools/).

{{< thumbcard src="/images/ui/workflows/builder-user-tools-library.png" alt="Builder library sidebar with the User tools group listing Atlassian CLI, AWS CLI, Google Cloud CLI, GitHub CLI, Maven, and five text summary starters" caption="Every installed tool gets its own named entry in the Builder library." position="top" >}}

## 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` |

{{< callout type="info" >}}
**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](/valdr/docs/workflows/user-tools/cli-adapters/#extend-a-starter-for-your-needs).
{{< /callout >}}

To install it:

1. [Build the `valdr-tools` archive](/valdr/docs/workflows/user-tools/starters/#build-and-import-the-pack) from its source in the `valdr-packs` repository.
2. Open **Settings > Valdr Packs > Import Pack**, select the archive, review the preview, and import.
3. 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](/valdr/docs/ui/workflows/#tools).

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.

1. 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.
2. In the inspector's **Inputs** section, choose the `text` input and enter the text to count.
3. Map the outputs you want later steps to use.
4. Choose **Test**, then open the run in **Runs** to see the result.

{{< thumbcard src="/images/ui/workflows/builder-user-tool-step.png" alt="Node text summary step on the Builder canvas with the inspector showing tool ID valdr-tools.user.node, action summarize, and the installed revision with its sha256 content hash" caption="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:

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

The successful result is:

```json
{"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](/valdr/docs/workflows/definition-authoring/#pin-a-user-tool).

## Host access and limits

{{< callout type="warning" >}}
User tools run on the workflow host with your user's permissions, just like [Command steps](/valdr/docs/workflows/steps/command/). 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.
{{< /callout >}}

**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:

```yaml
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](/valdr/docs/workflows/user-tools/runtime/#redaction-and-sensitive-output).

## Retries, cancellation, and recovery

- **Retry step** sends the step's original input with the same [`operationId`](/valdr/docs/workflows/user-tools/runtime/#whats-in-the-request) 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](/valdr/docs/workflows/reliability-and-recovery/#user-tool-attempts-and-uncertain-outcomes) 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](/valdr/docs/workflows/user-tools/maven/#send-a-failed-build-back-to-the-agent).

## Next step

Continue with [Session Steps](../session/) to add agent work. To write your own local action, follow [Build Your First Tool](/valdr/docs/workflows/user-tools/quickstart/). If a tool is missing or failing, see [workflow troubleshooting](/valdr/docs/workflows/troubleshooting/#a-user-tool-is-unavailable-or-fails).