Run your first workflow

This guide is for engineers using a Pyplines installation that their team already operates. You need the operator CLI, a server account, and access to an Environment. You do not need Docker, the SDK, or the Action authoring CLI on your workstation.

If you are setting up the platform, start with installation.

Install and connect

Install Python 3.12 or newer. In a virtual environment, install the pyplines-cli version from the site's supported tooling release, including the rc suffix for a release candidate:

python3 -m venv .venv
source .venv/bin/activate
# Replace TOOLING_VERSION with the supported tooling version.
python -m pip install 'pyplines-cli==TOOLING_VERSION'
pyplines version
pyplines login https://pyplines.example.com --username alice

On Windows, activate the virtual environment with .venv\Scripts\Activate.ps1 in PowerShell. Replace the example server URL and username with those supplied by your administrator. Login prompts for your password. For an organization CA, see CLI configuration.

Choose an existing Pypline

Your administrator or workflow owner should supply the Environment name and any required inputs. The following examples use development:

pyplines list --environment development
pyplines info development/example

Replace example with a name from the list. Inspect its Definition and input requirements before starting it: a Run can make real changes through its Actions. A Member can start permitted Runs; deploying a new Definition requires an Architect, Operator, or Admin assignment.

For a Pypline with no required inputs:

pyplines run start development/example --wait

For required inputs, create a JSON or YAML input file matching the Definition and pass --inputs ./inputs.json. Waiting follows the Run until it succeeds, is cancelled, blocks, becomes uncertain, or the CLI's wait timeout expires. Closing the CLI does not cancel the Run.

Deploy a small example

If you also have deployment access, the repository's echo example demonstrates input binding and output reuse without modifying an external service. It is a development example, not a published official catalog promise.

Before continuing, have your administrator publish the repository's examples/local/actions/echo Action as echo@2026.10.3 into the registry used by development, and admit a compatible runner. If your team publishes a different version, update both uses values below. Catalog guidance explains how to obtain existing Actions; operators do not need to build this example themselves.

Save these two files:

apiVersion: pyplines/v1
kind: Definition
name: echo-workflow
inputs:
  message:
    type: string
    default: Hello from operations
steps:
  - name: first
    uses: echo@2026.10.3
    with:
      message: "${{ inputs.message }}"
  - name: second
    uses: echo@2026.10.3
    with:
      message: "${{ steps.first.outputs.message }}"

{"message": "Checking the automation path"}

Validate, deploy, and start:

pyplines validate ./workflow.yaml
pyplines deploy ./workflow.yaml --environment development --as example
pyplines run start development/example --inputs ./inputs.json --wait

Local validation checks structure. Deployment checks Action availability and contracts, then pins image digests. If a policy requires approvals, an eligible approver must approve each prepared step before it proceeds.

Inspect the result

Use the Run ID returned by your command in place of 1:

pyplines run info 1
pyplines run attempts 1
pyplines run history 1
pyplines run logs 1 first

For the echo example, both steps should succeed and return the supplied message in their outputs. Attempts identify the individual executions; history records the Run's events. No sample output on this site represents a Run executed in your installation.

Continue with building Definitions, monitoring, or approvals.