A complete agent run

How an employee and their agent use Weldall CLI to access a company application securely.

This page follows a complete run from the perspective of an employee and their agent. The example uses an application that manages the company’s contracts.

1. The employee signs in

The employee signs in once through the CLI:

weldall login

The CLI opens the company’s sign-in page in the browser. After a successful login, it stores the session and device key in the operating system’s secure credential store.

The employee needs an effective weldall:login scope, assigned directly by email or through a matching provider group, before this CLI sign-in can complete. Browser sign-in to the Weldall administration UI is separate.

2. The employee gives the agent a task

Weldall is not tied to a specific agent. It works with Pi, Claude, and any other agent that can invoke the CLI. The agent initially needs to know only one rule:

Use Weldall for tasks in my company.

Administrators can add further company-specific guidance to the centrally managed CLI appendix. When the agent invokes weldall without a subcommand, the help output includes the locally cached appendix without making a network request. Login, status, scope, and skill commands refresh the cache for later invocations.

The employee then gives the agent the business task:

Find the contract with Nordstern GmbH and change its next review date to September 30, 2026.

The employee does not need to know which service manages contracts or how to call its API.

3. The agent discovers available skills

The agent first searches the locally cached catalog using concrete nouns and actions from the task:

weldall skills find "contract review date"

The search considers skill identifiers, titles, catalog previews, tags, owners, and resources. Multi-word searches rank skills matching more of the words first. A possible response is:

contracts.manage  Manage contracts  available

If no result matches, the agent should try fewer or broader words, such as the system, resource, or action. weldall skills is shorthand for weldall skills list and browses the complete visible catalog. Depending on its configuration, a visible skill can either be available or indicate missing permissions.

4. The agent reads the instructions

The agent loads the complete skill:

weldall skills show contracts.manage

The skill document tells the agent how to use the CLI for the correct HTTP requests. It contains complete weldall request commands with target URLs, scopes, and required data:

---
title: "Manage contracts"
requiredScopes:
  - "contracts:read"
  - "contracts:update"
---

Search for a contract:

```sh
weldall request \
  --scope contracts:read \
  "https://contracts.example.com/api/contracts?customer=<url-encoded-name>"
```

Ask the user for confirmation before making a change. Then update the review date:

```sh
weldall request \
  --method PATCH \
  --scope contracts:update \
  --json '{"nextReviewAt":"<YYYY-MM-DD>"}' \
  https://contracts.example.com/api/contracts/<contract-id>
```

In this example, confirmation is a rule defined by the skill. Weldall does not enforce the confirmation itself. Weldall enforces that the agent can use only approved targets and scopes.

5. The agent reads the contract

The agent follows the instructions and searches for the contract:

weldall request \
  --scope contracts:read \
  "https://contracts.example.com/api/contracts?customer=Nordstern%20GmbH"

The contract service might respond with:

{
  "id": "contract-4711",
  "customer": "Nordstern GmbH",
  "nextReviewAt": "2026-06-30",
  "status": "active"
}

The agent now knows the current value and asks the employee for the confirmation required by the skill.

6. The agent updates the contract

After confirmation, the agent sends the change:

weldall request \
  --method PATCH \
  --scope contracts:update \
  --json '{"nextReviewAt":"2026-09-30"}' \
  https://contracts.example.com/api/contracts/contract-4711

The CLI prints the contract service’s response. The agent summarizes the result for the employee.

What Weldall handles

For every weldall request, the CLI performs the security-sensitive steps itself:

It verifies that the target URL belongs to a registered company service.
It verifies that the requested scope is supported by the service and assigned to the employee.
It obtains short-lived, DPoP-bound credentials for that specific service.
It sends the API request directly to the contract service.
It returns only the business response to the agent.

The agent never sees an access token and does not need to store credentials. Administrators centrally control which skills are visible and which scopes an employee may use. Weldall records whether the requested authorization was granted or denied.

Connect your own services to Weldall

Before an agent can access a company service, administrators connect that service to Weldall once. They define the permissions and publish a matching skill. Employees can then use the service without needing to understand its API, URLs, or authorization model.

See How to: Integrate a service for the individual steps.