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

pyplines auth login --username root
pyplines project create production --name Production
pyplines project use production
pyplines project settings set .region '"us-east-1"'
pyplines project policy inspect
pyplines project policy update --network-egress enabled

pyplines function check ./functions/restart-service
pyplines function run ./functions/restart-service --input service=api
pyplines function package ./functions/restart-service
pyplines apply ./functions/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 Functions. Project policy is the enforced operational boundary for network, concurrency, retry, resource, and data-size limits. Policy updates display a Plan and require confirmation; automation and JSON mode must pass --auto-approve.

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:

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 packages source with the same Docker-backed pyplines function implementation used for local development, targeting 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:

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:

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:

pyplines secret set openai

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

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:

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.

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:

pyplines --verbose-errors function run --input value=123

--verbose-errors is intentionally independent from --verbose: the former expands failures, while the latter expands successful resource views. Error output is always redacted and never includes secret values or raw rejected Function inputs. Automation 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.