Metadata-Version: 2.4
Name: pyplines-cli
Version: 2026.8.1a4
Summary: The official command-line interface for Pyplines
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: click>=8.4.2
Requires-Dist: cryptography<47,>=45
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: humanize<5,>=4.16
Requires-Dist: jsonschema<5,>=4.25
Requires-Dist: pathspec<1,>=0.12
Requires-Dist: pyyaml<7,>=6
Requires-Dist: rich<15,>=14
Requires-Dist: typer<1,>=0.24

# Pyplines CLI

The CLI is the human-friendly and automation-safe interface to a Pyplines
installation. It uses the public Core API and does not shell out to `kubectl`.

## Core model

- A Procedure is immutable, versioned Library content.
- A Pypline is a Project-scoped executable that binds a Procedure to Project
  settings, Secrets, participants, and policy.
- `apply` plans and applies Function Packages, digest-pinned Function images,
  Procedures, Pyplines, directories, and Pypline Packages according to their
  contract.

## Typical workflow

```console
pyplines auth login --username root
pyplines project create production --name Production
pyplines project use production

pyplines apply ./dist/restart-service.function.tar.gz
pyplines apply restart-production.procedure.yaml
pyplines apply restart-production.pypline.yaml

pyplines list
pyplines inspect restart-production
pyplines run restart-production --input service=api
pyplines history restart-production
pyplines inspect restart-production --run latest
pyplines logs restart-production
pyplines artifacts list --from restart-production
pyplines artifacts inspect report --from restart-production
pyplines artifacts download report --from restart-production --as restart-report.pdf
```

`artifacts download [name] --from <pypline>` resolves the latest Run to an exact number,
verifies the Artifact digest, and preserves its original filename unless
`--as` supplies a local destination. The name may be omitted when the Run has
exactly one output Artifact. Use `--run <number>` for historical Artifacts and
`--force` to replace an existing local file.

Human mode renders a `Plan` table and prompts `Approve [y/N]` before changing
state. Use `--dry-run` to inspect the Plan without changing state and
`--auto-approve` for deliberate non-interactive application.

An application directory can be planned and applied as one unit:

```console
pyplines apply ./restart-production --project production --dry-run
pyplines apply ./restart-production --project production
```

An ordinary directory recursively discovers prepared Function Packages and
authored Procedure and Pypline documents. A directory rooted by
`pyplines-package.yaml` is a Pypline Package: the CLI discovers Function source
projects beneath `functions/`, Procedures beneath `procedures/`, and Pyplines
beneath `pyplines/`. It delegates source packaging to `pyplines-function` for
the installation architecture. Both modes order bundled dependencies, render
one combined Plan, request approval once, and apply resources sequentially so a
failed apply can be corrected and safely resumed.

Human application displays real preparation, planning, and application
progress. Interactive terminals receive a live count-based progress bar with
the active resource and elapsed time; redirected human output receives discrete
milestones. Progress stops before the Plan and `Approve` prompt. It measures
completed work items rather than predicting completion time. Progress is sent
to stderr and is omitted entirely from JSON and automation output.

Inspect a Package locally before applying it:

```console
pyplines inspect ./restart-production
pyplines inspect ./restart-production --verbose
pyplines --output json inspect ./restart-production
```

The default screen summarizes Package contents, resource dependencies,
external dependencies, and named supporting content. Verbose mode adds the
deterministic apply order, source paths, digests, Package root, and discovery
rules. Package inspection is offline; use `apply --dry-run` when installation
readiness and the mutation Plan are required.

Place a `.pyplinesignore` file at the application root to exclude local
variants or generated content. Its syntax follows Git ignore rules. Common
development directories such as `.git`, `.venv`, `node_modules`, and
`__pycache__` are excluded automatically. Duplicate resource identities and
bundled dependency cycles fail before the Plan is displayed. Symbolic links
are rejected to keep discovery inside the selected directory. A snapshot digest
also prevents applying when discovered sources change after planning.

Valid resources with unavailable external dependencies produce a blocked Plan
and a human-readable `Missing Requirements` table. A missing Project Secret,
for example, identifies the Secret, selected Project, requiring Pypline, and
safe `pyplines secret set` command. Blocked Plans never prompt for approval or
mutate resources. Dependencies supplied in the same directory are marked
prospective and do not block the combined Plan.

Library discovery and lifecycle management use one flat surface:

```console
pyplines library list --kind function
pyplines library inspect restart-service@1.0.0
pyplines library disable function:restart-service@1.0.0
pyplines library enable function:restart-service@1.0.0
pyplines library remove function:restart-service@1.0.0 --auto-approve
```

String Secrets use a protected prompt and are created or rotated with the same
command:

```console
pyplines secret set openai
```

Automation can use stdin or an environment-variable name without putting the
value in process arguments:

```console
printf '%s' "$OPENAI_API_KEY" | pyplines secret set openai --from-stdin
pyplines secret set openai --from-env OPENAI_API_KEY
```

Secret list, inspection, and history responses contain metadata and digests,
never plaintext values. `project secret` remains the advanced interface for
custom JSON schemas and non-string JSON values.

Root manages non-human identities through the first-class Robot surface. All
commands use stable names rather than internal identifiers:

```console
pyplines robot create benchmark-runner --name "Benchmark Runner"
pyplines robot role grant benchmark-runner publisher \
  --library-kind function --family-prefix benchmark-
pyplines robot role grant benchmark-runner administrator --project benchmark
pyplines robot token create benchmark-runner local-development --expires-in 90d
pyplines robot inspect benchmark-runner
```

The raw Access Token is returned only by `robot token create`; store it in a
secret manager at that point. `robot token list` and `robot token inspect`
return metadata only. Tokens are revoked by name, and disabling or retiring a
Robot revokes all of its active tokens. Robots may hold Publisher,
Administrator, Operator, and Consumer roles; Root and Approver remain
human-only.

Human-friendly Rich text is the default. `--output text|json` selects the
presentation for one command. Set `PYPLINES_AUTOMATION_MODE=enabled`, or put
`automation_mode: enabled` in the CLI configuration, to default all commands
to JSON and disable interactive behavior. An explicit output format changes
presentation only; it does not enable or disable automation safeguards.

Run and Pypline inspection use condensed operational screens by default.
`--verbose` retains those layouts while adding exact timestamps, immutable
identities, resolved dependencies, bindings, policy, and other authorized
diagnostic detail.

Successful output uses stdout, errors use stderr, and JSON responses preserve
the authoritative API representation. The server and Project can be supplied
with `PYPLINES_SERVER_URL` and `PYPLINES_PROJECT` or `--server` and
`--project`.
