Metadata-Version: 2.4
Name: oceanum-prax-cli
Version: 0.3.2
Summary: Command-line interface for PRAX platform
License-Expression: MIT
Keywords: prax,cli,deploy
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Development Status :: 3 - Alpha
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: textual<1,>=0.79
Requires-Dist: oceanum-prax-sdk==0.3.2
Requires-Dist: httpx>=0.27.0
Requires-Dist: requests>=2.31.0
Requires-Dist: oceanum>=1.2.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.1.0; extra == "test"
Provides-Extra: dev
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.11.0; extra == "dev"
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.12; extra == "dev"
Dynamic: license-file

# oceanum-prax-cli

PRAX project, pipeline, deployment, and operations commands for the Oceanum CLI.

Use **`oceanum prax`** to work with PRAX from your terminal. The interactive console
is available as `prax-console`.

## Command surface

The inventory below includes every visible command and nested subcommand registered
with the Oceanum CLI. Indentation indicates nesting: for example, `pipeline` →
`triggers` → `pause` means `oceanum prax pipeline triggers pause`.

<!-- cli-command-surface:start -->
```text
oceanum prax
  artifacts — Inspect retained build artifacts.
    list
    show
  builds — Build inspection commands
    list
    logs
    show
  deploy — Deployment management commands
    list
    show
    spec
    watch
  health — Health check and observability commands
    project
    stage
    summary
  init — Scaffold ProjectSpecs and CI pipelines.
    ci
    connections
  logs — Stream deployment logs to stdout
  notifications — Notification history, configuration, and delivery observability
    channels
      create
      delete
      list
      show
      update
    deliveries
      list
    list
    org-alerts
      list
      set
      unset
    subscriptions
      create
      delete
      list
      show
      update
  operations — Inspect and control durable stage deployment operations.
    cancel
    list
    recover
    replace
    show
    watch
  org — Organization management commands
    create
    deprovision
    list
    provision
    quota
    set-tier
    show
    tiers
    usage
  pipeline — Pipeline management commands
    cycles
    list
    logs
    resubmit
    retry
    run
    runs
    show
    stop
    terminate
    triggers
      pause
      resume
      show
  project — Project management commands
    archive
    delete
    deploy
    edit
    export
    history
    history-compare
    history-get
    list
    show
    status
  route — Route inspection and permissions commands
    list
    permissions
      get
      set
  secret — Manage PRAX-backed credential secrets.
    delete
    list
    migrate-owner
    preflight
    set
    show
  service — Service inspection commands
    health
    instance
    list
    logs
    metrics
    show
    status
    usage
  stage — Inspect and operate immutable stage releases.
    approve
    candidate
    compare
    deploy-direct
    evaluate
    history
    promote
    retry-delivery
    rollback
    rollback-preview
    show
  template — Project template commands
    deprecate
    diff
    list
    publish
    scaffold
    source
    validate
    versions
  user — User inspection commands
    list
    show
  validate — Validate a PRAX ProjectSpec file
```
<!-- cli-command-surface:end -->

Use `oceanum prax --help` or append `--help` to any command path for its arguments,
required options, and output formats. Account-backed commands require authentication;
use `oceanum auth login` to establish an interactive session.

### Examples

These show command syntax, not pre-existing resources. Substitute your project,
pipeline, deployment, stages, and release number. `project.yaml` is a local complete
ProjectSpec. Promotion requires an eligible source release and appropriate access.

<!-- cli-examples:start -->
```bash
# Validate a local ProjectSpec, then create or replace its project configuration.
oceanum prax validate project.yaml
oceanum prax deploy spec project.yaml --reason "Apply example project"

# Inspect/export the authored project and retained build observations.
oceanum prax project status forecast-project
oceanum prax project export forecast-project --output yaml
oceanum prax builds list --project forecast-project

# Run a pipeline at an explicit project-owned stage binding.
oceanum prax pipeline run forecast --project-ref forecast-project --stage-ref dev --watch

# Preview a project-wide authored trigger change without submitting it.
oceanum prax pipeline triggers pause forecast-project forecast --dry-run

# Inspect immutable stage releases and promote a pinned source release.
oceanum prax stage history --project forecast-project --stage dev
oceanum prax stage promote --project forecast-project --stage prod --from-stage dev --release 3 --idempotency-key promotion-001 --reason "Promote reviewed release"

# Stream deployment logs.
oceanum prax logs forecast-deployment --follow
```
<!-- cli-examples:end -->

Pipeline trigger pause/resume edits the common authored `triggers.enabled` setting
for every stage that references that pipeline. It validates and previews the change
before confirmation; `--dry-run` previews without submitting a revision. Recovery of
events received while paused is not guaranteed. Check each stage's observed binding
state after deployment to verify that the change has taken effect.

## Requirements

Python **3.11+** and Oceanum CLI **1.2.0+** are required. The Python distribution is
named `oceanum-prax-cli` and integrates with the Oceanum CLI. Its dependencies and version
bounds are declared in `pyproject.toml`.

## Versions

The CLI and SDK share the same release version. Each CLI release depends on the
matching `oceanum-prax-sdk` release.

## See also

- [PRAX Python SDK](https://github.com/oceanum/prax-sdk)

### Pipeline discovery

`oceanum prax pipeline list --project forecast-project --stage dev --limit 20`
loads a bounded server definition page. Search filters pipeline/project names;
stage filters authored membership, not readiness. Each returned stage binding is
shown independently with its latest execution outcome; no global phase or
pipeline-wide health is inferred. `--limit` bounds definitions, never truncates a
sibling stage binding. Use `--offset` for another server page. Run admission still
requires an explicit project and stage and fresh server validation.
