Skip to content
Documentation
Valdr Workflows
Build User Tools
Use the Starter Pack

Use the Starter Pack

Sovereign

Don’t start from a blank file. The valdr-tools starter pack gives you working tools you can run today and copy tomorrow: the same example action in five languages, read-only adapters for four popular CLIs, and a Maven build tool with its own guide, Maven Builds.

The source lives in the valdr-packs repository under valdr-packs/valdr-tools. Treat that source as the one copy you maintain; generated archives and installed tools are outputs. Workflows > Tools shows which revisions are installed on your host.

Language starters

Each language starter implements the same harmless summarize action, so you can compare them side by side and copy the one that matches your stack.

Library entryTool IDRuntime already installed on the workflow host
Node text summaryvaldr-tools.user.nodeNode
Typescript text summaryvaldr-tools.user.typescriptBun
Python text summaryvaldr-tools.user.pythonPython 3
Shell text summaryvaldr-tools.user.shellPOSIX sh and jq
Native text summaryvaldr-tools.user.nativeA compiled valdr-tools-native binary on the host’s PATH

The native starter includes Go source. Build it yourself from the valdr-packs checkout:

mkdir -p build/bin
go build -trimpath -o build/bin/valdr-tools-native \
  valdr-packs/valdr-tools/tools/native/main.go

Add that checkout’s absolute build/bin directory to PATH before starting Valdr. Import never compiles anything, and the pinned Go source doesn’t vouch for the binary you install.

CLI starters

Put your existing CLIs to work in a workflow. Each adapter runs a fixed set of read actions against the CLI on the workflow host, using the configuration and sign-in you already have.

These are starters, not complete CLI wrappers. They cover useful read actions, not every command. Installing a CLI doesn’t add its other commands to Valdr; extend a starter to add the commands and flags your workflows need.
Library entryTool IDRead actions
GitHub CLIvaldr-tools.user.ghrepo-view, repo-list, pr-list, pr-view, issue-list, issue-view, run-list, run-view, workflow-list, release-list, release-view, label-list
AWS CLIvaldr-tools.user.awssts-get-caller-identity, s3-list-buckets, ec2-describe-instances, ec2-describe-volumes, ec2-describe-vpcs, iam-list-users, lambda-list-functions, rds-describe-db-instances, dynamodb-list-tables, ecr-describe-repositories
Google Cloud CLIvaldr-tools.user.gcloudprojects-list, projects-describe, compute-instances-list, compute-instances-describe, compute-disks-list, compute-networks-list, storage-buckets-list, run-services-list, run-services-describe
Atlassian CLIvaldr-tools.user.aclijira-workitem-view, jira-workitem-import, jira-workitem-search, jira-workitem-keys, jira-project-list, jira-project-view, jira-workitem-comment-list, jira-workitem-attachment-list, jira-workitem-link-list, jira-workitem-list-watchers, jira-board-search, jira-board-view

Every CLI adapter also has a version action. It takes {} and returns {"version":"..."}, a quick local check that the CLI is installed. It doesn’t check sign-in or account access.

What to expect from the adapters:

  • Typed inputs, no pass-through. Each action accepts validated fields, never arbitrary arguments.
  • The CLI’s own JSON as output. Most actions return the CLI’s JSON unchanged, so run one against a real account and look at the result before you map fields.
  • Jira fields that line up with Valdr tasks. jira-workitem-import reads one work item by key and returns fixed fields: key, title, type, jiraType, priority, jiraPriority, labels, status, and descriptionMarkdown. type and priority use the same values as Valdr tasks: type is bug, story, epic, or spike when the Jira type matches, and task otherwise, and priority turns Jira’s Highest through Lowest into 1 through 5, or null for any other priority. The original Jira values stay in jiraType and jiraPriority. Every field is declared in the output schema, so later steps can map them with confidence.
  • Every matching key. jira-workitem-keys returns keys, the key of every work item that matches a JQL query, while jira-workitem-search stops at 100 items. A very large result can run past the adapter’s time or size limit, so narrow the JQL if the step fails.
  • Useful failures. When the CLI exits with an error, the failure includes its exit code or signal and a shortened diagnostic message. Redaction is best effort; review CLI output before sharing it. Atlassian failures may also include sign-in diagnostics to help you correct account access.
  • No credential changes. The adapters never sign in or change credentials.

Each adapter has its own folder (tools/gh, tools/aws, tools/gcloud, tools/acli) with its own manifest and runner. Copy and customize a starter to add the actions your workflows need.

Build and import the pack

With Bun and the latest Valdr CLI installed, run this from your valdr-packs checkout:

make build-valdr-tools

This validates the pack and writes build/valdr-tools.valdr-pack.tar.gz. Import the archive from Settings > Valdr Packs.

Install the runtimes and CLIs needed by the tools you plan to run, as listed above.

Before you rely on a CLI action, run it in a test workflow against a repository, account, project, or Jira item you know. Check the returned JSON, and see how missing sign-in, missing permissions, and bad identifiers are reported.

Next step

Run your first installed tool, then Build Your First Tool to learn how the files fit together.

Build Your First Tool