Metadata-Version: 2.4
Name: pyplines-cli
Version: 2026.9.8a1
Summary: The official command-line interface for Pyplines
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pyplines-cli-common>=2026.9.4a2
Requires-Dist: click>=8.4.2
Requires-Dist: filelock<4,>=3.18
Requires-Dist: httpx<1,>=0.28
Requires-Dist: jsonschema<5,>=4.25
Requires-Dist: referencing<1,>=0.36
Requires-Dist: pyyaml<7,>=6
Requires-Dist: typer<1,>=0.24

# Pyplines CLI

Deliver prepared automation and operate it through the public v1alpha1 Server API.
The CLI needs neither Docker access nor the Action SDK.

```sh
pip install pyplines-cli
pyplines --server https://pyplines.example.com auth login --email you@example.com
pyplines --workspace operations init restart-payments --from ./maintenance.tar.gz --file production.yaml
# Edit production.yaml as needed.
pyplines --workspace operations deploy production.yaml
pyplines --workspace operations run restart-payments --input service=payments
pyplines --workspace operations logs restart-payments
```

For a fresh local development appliance, run from the repository root:

```sh
pyplines --server http://127.0.0.1:18085 bootstrap \
  --bootstrap-token-file .local/docker/pyplines-bootstrap-token
pyplines auth whoami
pyplines list
```

Bootstrap prompts for a Workspace, administrator email, and confirmed password,
then saves the session and selects that Workspace. The CLI reads only the token
file, never `.local/docker/pyplines.env` or other appliance settings. Supply the
Server address with `--server` or `PYPLINES_SERVER_URL`. Bootstrap checks its
status before prompting: if already complete, it reports that no changes were
made and exits successfully. It never resets an existing installation.

For other installations, supply the token using `--bootstrap-token-file` or
`PYPLINES_BOOTSTRAP_TOKEN`, or enter it at the hidden prompt. No token/password
value flags are provided. For noninteractive use:

```sh
pyplines --server https://pyplines.example.com bootstrap \
  --email you@example.com --workspace operations \
  --bootstrap-token-file /secure/bootstrap-token \
  --password-file /secure/admin-password --json
```

Keep these input files private (for example, mode `0600` on Unix). Only the
session is saved locally, not the bootstrap token or password. A lost connection
can occur after bootstrap commits: try login before retrying. Successful
initialization is not rolled back if saving the local session fails.

Password login
creates a managed session under `~/.pyplines/credentials/`. Passwords are not saved.
Use `PYPLINES_ACCESS_TOKEN` for ServiceAccount automation, `--json` for structured
output, and `run -d` for detached execution. `auth logout` revokes the saved session.

Requires the Docker v1alpha1 Server with migrations through `20260912000200`.

Attached Runs print declared outputs after completion. Use `pyplines runs inspect
NAME NUMBER` for operational details; execution phase observations are exported
through the structured event system, not a deep diagnostics CLI view.
Installation prepares all Action images before activation; `pyplines repair NAME`
restores missing pinned images without upgrading. See
[installation readiness](../docs/installation-readiness.md) for registry configuration
and recovery behavior.
It does not support the retired Core/Project API. Upgrading the package replaces
the old command surface; legacy credentials are not imported automatically.

`pyplines version` reports the installed CLI package version (including editable
development suffixes) without connecting to the Server. Use `pyplines version
--json` for structured output; this is the client version, not the Server version.

Commands: `version`, `bootstrap`, `inspect`, `init`, `deploy`, `export`, `repair`, `uninstall`, `list`,
`status`, `run`, `logs`, `runs list|wait|cancel`, and `auth login|whoami|logout`.
Configuration files use JSON-compatible YAML. Human-readable static text is the
default; automation never encounters implicit prompts. Explicit login requires a
terminal. Approvals and missing inputs are handled through authorized Page/API
interactions, not CLI prompts.

See [declarative deployments](../docs/declarative-deployments.md) for registry
trust, Workspace grants and the initialize/edit/deploy workflow.

See [operation details](pyplines_client/README.md) for delivery semantics, limits,
authentication, and qualification. The old `cli/` sources are historical reference
only and are excluded from both wheel and source distribution.
# Shared CLI behavior

Human mode is the default: Typer help and readable results, with Rich tables on
interactive terminals. `AUTOMATION_MODE=enabled` or `--json` enables structured
JSON output and disables prompts. Results go to stdout; errors and progress go
to stderr. Streaming logs use newline-delimited JSON in automation mode.
Use `version` or `--version` without a Server connection. Diagnostic exception
types are available through `--verbose-errors` or `PYPLINES_VERBOSE_ERRORS=true`.
# Fresh installations and saved sessions

Bootstrap defaults to Workspace `default`. Interactive password validation retries
in place; automation must supply email, a password file, and a bootstrap token
source. `AUTOMATION_MODE=enabled` never prompts and produces JSON output.

Sessions are bound to the Server URL and its database-backed installation ID.
After a successful bootstrap/sign-in, the CLI atomically saves the verified
session. Reinstalling at the same URL does not attempt to revoke a session from
the previous installation. Sessions without an installation ID are not assumed
to belong to the new installation. Failed sign-ins and concurrent session
replacements preserve existing credentials. No automatic global credential
pruning is performed.
## Install from an OCI registry

```sh
pyplines inspect oci://ghcr.io/acme/maintenance:1.2.0
pyplines config oci://ghcr.io/acme/maintenance:1.2.0 > production.yaml
pyplines install oci://ghcr.io/acme/maintenance:1.2.0 --config-file production.yaml
pyplines upgrade restart-payments --dist oci://ghcr.io/acme/maintenance:1.3.0 --config-file production.yaml
```

All these commands also accept local archives. Registry references require an
explicit tag or digest. Tags are resolved once per command; use the digest from
`inspect` across commands when you need a fixed publication throughout review.
The CLI verifies registry payload integrity; the Server independently verifies
publisher trust before installing. Inspection does not imply publisher approval.

Registry downloads use direct HTTP APIs, not Docker. Credentials come from
`PYPLINES_REGISTRY_CONFIG_FILE` or Docker-compatible configuration and helpers.
Platform sessions and Action image-pull credentials remain separate. TLS is
required; `PYPLINES_REGISTRY_ALLOW_HTTP=localhost:5000` is an explicit local-test
exception. Registry transport does not read `.netrc` or implicit proxy settings.
