Metadata-Version: 2.4
Name: pyplines-cli
Version: 2026.7.4a1
Summary: The official command-line interface for Pyplines
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: dynaconf[yaml]<4,>=3.2.7
Requires-Dist: filelock<4,>=3.18
Requires-Dist: httpx<1,>=0.28
Requires-Dist: httpx-sse<1,>=0.4
Requires-Dist: pyyaml<7,>=6
Requires-Dist: rich<15,>=14
Requires-Dist: typer<1,>=0.24

# 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

```console
pip install pyplines-cli
```

## Configuration

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

```console
pyplines config path
```

Initial shape:

```yaml
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:

```console
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:

```console
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:

```console
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:

```console
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:

```console
pyplines function dev init hello-world
```

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

```console
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:

```console
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:

```console
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:

```console
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:

```console
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:

```console
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:

```console
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:

```console
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:

```console
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:

```text
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](https://github.com/pyplines/pyplines/blob/main/cli/changelog.md).
