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

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:

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:

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:

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:

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

{"$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:

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:

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.