Metadata-Version: 2.4
Name: pyplines-cli
Version: 2026.9.1a2
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: docker<8,>=7.1
Requires-Dist: filelock<4,>=3.18
Requires-Dist: httpx<1,>=0.28
Requires-Dist: httpx-sse<1,>=0.4
Requires-Dist: jsonschema<5,>=4.25
Requires-Dist: pathspec<1,>=0.12
Requires-Dist: pyyaml<7,>=6
Requires-Dist: rich<15,>=14
Requires-Dist: textual<7,>=6
Requires-Dist: typer<1,>=0.24

# Pyplines CLI

The CLI is the automation-first interface to a Pyplines installation. Standard
commands emit compact JSON, use stderr for errors, and never prompt. The
interactive `console` is the intentionally visual operating experience. Both
surfaces use the public Core API and shared application services; neither
shells 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 Action Packages, digest-pinned Action images,
  Procedures, Pyplines, directories, and Pypline Packages according to their
  contract.

## Typical workflow

```console
printf '%s' "$PYPLINES_PASSWORD" | pyplines auth login --username root --password-stdin
pyplines project create production --name Production
pyplines project use production
pyplines project settings set .region '"us-east-1"'
pyplines policy view
pyplines apply project-policy.yaml

pyplines action check ./actions/restart-service
pyplines action run ./actions/restart-service --input service=api
pyplines action package ./actions/restart-service
pyplines apply ./actions/restart-service
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
```

Project settings are authored configuration consumed by Procedures and
Actions. Effective Policy is the enforced operational boundary for network,
concurrency, retry, resource, and data-size limits. Use `apply --dry-run` to
obtain the complete apply plan before changing state. A normal `apply` executes
without an interactive confirmation.

`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.

`apply --dry-run` returns one `pyplines.dev/apply-plan/v1` document. A completed
apply returns one `pyplines.dev/apply-result/v1` document. Package preparation
and planning do not add terminal status output, so stdout remains safe to pipe
to tools such as `jq`.

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 Action Packages and
authored Procedure and Pypline documents. A directory rooted by
`pyplines-package.yaml` is a Pypline Package: the CLI discovers Action source
projects beneath `actions/`, Procedures beneath `procedures/`, and Pyplines
beneath `pyplines/`. It packages source with the same Docker-backed `pyplines
action` implementation used for local development, targeting the installation
architecture. Both modes order bundled dependencies, return one combined Plan,
and apply resources sequentially so a failed apply can be corrected and safely
resumed.

Inspect a Package locally before applying it:

```console
pyplines inspect ./restart-production
```

Package inspection returns contents, resource dependencies, external
dependencies, named supporting content, deterministic apply order, paths, and
digests. It 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.
A missing Project Secret, for example, identifies the Secret, selected Project,
requiring Pypline, and safe `pyplines secret set` command. Blocked Plans do not
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 action
pyplines library inspect restart-service@1.0.0
pyplines library disable action:restart-service@1.0.0
pyplines library enable action:restart-service@1.0.0
pyplines library remove action:restart-service@1.0.0
```

String Secrets are created or rotated from stdin or a named environment
variable so secret material is not exposed 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 action --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.

Standard commands always emit one compact JSON document followed by a newline.
Streaming commands such as `logs --follow` emit JSON Lines. There is no output
mode switch and no automation-mode setting; scripts and engineers observe the
same stable contract. Successful output uses stdout and failures use stderr.
Canonical `$schema` references are rooted at
`https://v1.pyplines.dev/schemas/`.

A completed Run is the authoritative server representation, for example:

```json
{"$schema":"https://v1.pyplines.dev/schemas/Run.json","id":"7338cb42-c7e8-421c-b194-9eb1a30c7ae7","number":8,"project_id":"8bc93815-b9bb-4a9d-9b93-00490c6f59ef","status":"completed","input":{"name":"Dan"},"output":{"message":"Hello, Dan!"},"created_at":"2026-08-26T14:31:20Z","started_at":"2026-08-26T14:31:20Z","completed_at":"2026-08-26T14:31:21Z"}
```

## Interactive console

`pyplines console` opens a branded, Project-scoped operational workspace. It
uses the current Project unless `--project <slug>` selects a session-only
override:

```console
pyplines console
pyplines console --project production
```

The console starts with the Project's Pyplines, drills into their Runs and Run
Artifacts, and provides an Inbox split between authorized Approvals and Inputs.
Project administration, Policy authoring, Library management, and installation
lifecycle operations remain standard CLI or System Manager responsibilities.

Errors are concise and actionable by default. Use `--verbose-errors` for one
command, set `PYPLINES_VERBOSE_ERRORS=true`, or configure
`verbose_errors: true` to include safe technical diagnostics:

```shell
pyplines --verbose-errors action run --input value=123
```

Error output is always redacted and never includes secret values or raw
rejected Action inputs. Failures use a stable JSON `error` object with a
code, category, message, structured details, and an optional hint.

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`.
