pyplines-cli 2026.7.4a1

The official command-line interface for Pyplines

pyplines-cli

pyplines-cli is the command-line interface for Pyplines. It supports local Function development, deployed Pypline operation, and secure interaction with a Pyplines Server.

Install

pip install pyplines-cli

Configuration

Configuration is YAML stored at ~/.pyplines/config.yaml by default. Find the effective path with:

pyplines config path

Initial shape:

server:
  url: https://pyplines.example.com
  insecure: false
  connect_timeout: 5
  operation_timeout: 30

function:
  dev:
    url: http://127.0.0.1:7331
    connect_timeout: 5
    operation_timeout: 1800
    template:
      repository: https://github.com/pyplines/function-template.git
      ref: v1

PYPLINES_CONFIG_PATH overrides the configuration path. Principal Access Tokens are stored separately in ~/.pyplines/credentials.json; PYPLINES_CREDENTIALS_PATH overrides that path. On Unix-like systems, the CLI uses mode 0700 for the directory and 0600 for the credential file.

Every setting can be overridden with a PYPLINES_ environment variable. Use double underscores for nested keys:

export PYPLINES_MODE=automation
export PYPLINES_FUNCTION__DEV__URL=http://127.0.0.1:7331
export PYPLINES_FUNCTION_DEVELOPMENT_TOKEN="<local-container-token>"

The token is environment-only and is not written to the configuration file.

Server Authentication

Sign in through the server's configured local, OIDC, or SAML browser flow:

pyplines login --server-url https://pyplines.example.com
pyplines whoami
pyplines logout

HTTPS is required for non-loopback servers by default. An explicitly insecure server on a trusted network can be selected with:

pyplines login --server-url http://10.40.10.218:8080 --insecure

This permits cleartext HTTP; it does not disable certificate verification for HTTPS.

The CLI receives only a bounded Pyplines Access Token after browser approval. It never receives provider passwords, OIDC tokens, SAML assertions, or browser session cookies. PYPLINES_ACCESS_TOKEN overrides stored credentials for automation and is never persisted.

Output

Rich interactive output is the default. It uses purpose-built tables for collections, compact detail views for resources, and syntax-highlighted valid JSON when inspecting structured documents.

Collection tables adapt to the terminal width. Primary resource identifiers remain visible while less important columns are removed as space becomes constrained. Detail views group related fields into labeled sections and use consistent presentation for statuses, identifiers, timestamps, URLs, paths, booleans, sizes, and nested JSON values. Progress indicators are transient and errors are written to standard error. Use --verbose to include safe diagnostic metadata with human-readable errors.

Set the process-level mode to automation for compact JSON and NDJSON output:

PYPLINES_MODE=automation pyplines function dev status

Non-streaming operations emit one JSON document. Streaming operations emit one NDJSON event per line. Automation mode never emits styling, progress indicators, explanatory text, or human-formatted values. Responsive table and detail-view decisions never change the underlying automation payload.

Function Development

Commands under pyplines function dev operate on local Function source and the Function development environment. Other pyplines function commands operate on Functions registered with the authenticated server.

Initialize from the configured, pinned Git template:

pyplines function dev init hello-world

Check, invoke, and package any Function in the collection mounted into the development container:

cd hello-world
pyplines function dev status
pyplines function dev check
pyplines function dev invoke --input name=Ada
pyplines function dev invoke --input-file inputs.yaml
pyplines function dev package

function dev status reports development-service readiness, every discovered Function and environment state, and the target Python, Debian, and architecture. Use --verbose to include the container Function root, Python ABI, and service contracts.

function dev check presents the Function contract, each performed check, environment cache state, and compact input and output field tables. Failed checks retain completed outcomes and identify checks that were not run. Use --verbose to include schema constraints and the complete JSON Schemas.

Invocation prints only the Function output by default. Follow the live operation when progress and Function logs are needed:

pyplines function dev invoke --input name=Ada --follow

In automation mode, ordinary invocation emits one compact JSON output value and --follow emits the complete NDJSON event stream.

function dev init uses the system Git client and honors existing credential helpers, SSH agents, proxies, and enterprise Git configuration. It does not execute template hooks or retain the template repository's .git directory.

Function Registration

After packaging, register and browse the Function on the authenticated server:

pyplines function register dist/hello-world.function.tar.gz
pyplines function list
pyplines function get hello-world
pyplines function versions hello-world
pyplines function get hello-world@1.0.0

Function lists support server-side exact filters and cursor pagination:

pyplines function list --tag environment=development --limit 25
pyplines function list --cursor '<opaque-cursor>'

Update Function family metadata and the complete Resource Tag map with:

pyplines function update hello-world \
  --display-name "Hello World" \
  --description "Example Function" \
  --tag environment=development

Delete a Function Version or an empty Function family after confirmation:

pyplines function delete hello-world@1.0.0
pyplines function delete hello-world

Automation mode requires --yes for deletion and never prompts.

Pyplines And Runs

Pyplines use direct commands because they are the primary resource operated by the CLI:

pyplines deploy pypline.yaml
pyplines list
pyplines get deploy-site
pyplines delete deploy-site

Trigger a Run through a Pypline's manual trigger. Input assignments override values loaded from a YAML or JSON input file:

pyplines trigger deploy-site --input environment=production
pyplines trigger deploy-site --input-file inputs.yaml --follow
pyplines trigger deploy-site --via operator --input revision=abc123

--via can be omitted when the Pypline has exactly one manual trigger. --follow attaches to the Run's resumable log stream and waits for its terminal state.

Existing Runs and their Step Executions are addressed beneath the run resource:

pyplines run list deploy-site
pyplines run get <run-id>
pyplines run output <run-id>
pyplines run logs <run-id> --follow
pyplines run cancel <run-id>

pyplines run step list <run-id>
pyplines run step get <run-id> <step-execution-id>
pyplines run step output <run-id> <step-execution-id>
pyplines run step logs <run-id> <step-execution-id> --follow
pyplines respond <run-id> --input decision=continue

Run and Step outputs preserve any valid JSON type. Log streams use NDJSON in automation mode and the common human-readable log presentation in interactive mode.

Versioning

The CLI uses calendar versioning with Python-compatible prerelease identifiers:

YYYY.MONTH.REVISION{PRERELEASE}

For example, the 2026.7.1 release can progress through:

Version	Meaning
2026.7.1a1	First alpha
2026.7.1a2	Second alpha
2026.7.1b1	First beta
2026.7.1rc1	First release candidate
2026.7.1	Stable release

Published versions are immutable. Corrections require another prerelease number. The revision advances for the next body of work released in the same month; the year and month follow the release date. Prerelease identifiers follow PEP 440.

Release history is maintained in the CLI changelog.