Skip to content
Documentation
Valdr Workflows
Build User Tools
Package, Import, and Update

Package, Import, and Update

Sovereign

Your program passed its direct test. Now make it a workflow step: validate and package the files, import the pack, and add the tool in the Builder. The steps below continue the my-tools example.

Validate and package

Run these from the directory containing my-tools, using a Valdr CLI that supports user tools:

valdr validate-pack my-tools
valdr generate-valdr-pack my-tools \
  --output build/my-tools.valdr-pack.tar.gz \
  --exported-at 0

validate-pack checks every manifest, schema, and inventoried file before anything reaches Valdr. --exported-at 0 fixes the archive timestamp so the same source always produces the same archive. Neither command runs your tool.

Keep pack.yaml, the manifest, and your program in version control. The generated archive is a build output, so don’t edit it by hand.

Import and inspect

  1. Open Settings > Valdr Packs > Import Pack and select build/my-tools.valdr-pack.tar.gz.
  2. Review the preview: tool IDs, revisions, content hashes, files, and what each tool will run. Then import.
  3. Open Workflows > Tools and select Text summary to check its details and manifest.
Every installed tool, its revision, and its pack in one catalog.

Try it in a disposable environment first. A valid archive proves the pack is well formed; only a real run proves the runtime is installed and the action works on that host.

Run your tool in a workflow

  1. Open a draft workflow in the Builder and add Text summary from the User tools library group. Its single action, summarize, is selected automatically.
  2. In Inputs, choose text and enter some text, for example Hello Valdr followed by a new line and Tools are ready. Leave Working directory (cwd) empty; this action doesn’t read files.
  3. Map outputs to $.normalized.data.characters, $.normalized.data.words, and $.normalized.data.lines.
  4. Choose Test and open the run in Runs. Expect 28 characters, 5 words, and 2 lines.
  5. Use the outputs downstream. For example, ${steps.summarize.outputs.words} works when this step’s key is summarize and the consuming step declares needs: [summarize].

In YAML, the step’s inputs and output mappings sit beside the tool reference the Builder created:

# Fragment of the step selected in the Builder; keep its tool reference.
inputs:
  text: "Hello Valdr\nTools are ready."
outputs:
  characters: "$.normalized.data.characters"
  words: "$.normalized.data.words"
  lines: "$.normalized.data.lines"

The Builder writes the full tool reference: ID, action, revision, content hash, and both schemas. If you edit YAML by hand, copy that reference from the Builder rather than typing a hash. See Pin a user tool.

To run the tool in a specific folder, add cwd beside tool and inputs, for example cwd: ./scripts. Relative paths resolve from the workflow’s worktree or project repository, and the folder must already exist. cwd configures the step, so never put it inside inputs.

Ship a new revision

Tool revisions are how you change behavior without surprising anyone:

  1. Update the program and bump revision in the manifest. In the example, also update the program’s toolRevision check, and its toolId check if you chose your own ID, plus your direct-test request.
  2. Validate, package, and import the new archive.
  3. In each workflow that should get the change, select the new revision in Installed revision and save a new workflow version.

New steps use the newest installed revision. Existing steps and past runs keep their original pins until you choose otherwise.

Valdr rejects an existing tool ID and revision that arrive with different content, even if that revision was removed from the catalog, so bump the revision whenever anything in the manifest or its listed files changes. Only one revision of each tool can be in a single pack archive.

Export and share

Export carries the tool’s source files and the pins that workflows reference, so a teammate can import the same reviewed revision. It doesn’t carry environment values, runtimes, dependencies, or CLI sign-ins. Each host supplies its own. A pinned tool doesn’t pin the version of an external CLI it calls.

Each archive supports one revision per tool ID. Export fails if the included workflows pin different revisions of the same tool. Export includes every active workflow version in the selected packs, so saving a newer workflow version doesn’t exclude older active versions. You can select packs to export, but not individual workflow versions within a pack.

To share workflows with different pins:

  • Export separate pack selections when each selection uses only one revision of each tool.
  • If the conflict is within one pack, build separate archives from maintained source, each containing one revision of each tool and only workflows pinned to those revisions. Keep the tool IDs and owning pack value unchanged so the receiving host can import both revisions. Validate each archive before sharing it.

Next step

Test and troubleshoot your tool before you share the pack.

Build Your First ToolWrap a CLI