CLI support to pause, cancel, and resume Pipeline Runs

Summary

Add a new CLI command pipelinerun to manage the lifecycle of a Pipeline Version Run.
This includes the ability to pause, cancel, and resume a pipeline run directly from the CLI.

A shorthand alias pr should also be supported.

What needs to be implemented

New CLI commands

The pipeline_version_run_id should be accepted either as:

• a positional argument or
• an explicit flag --pipeline_version_run_id

Preferred (positional) usage

clarifai pr pause   <pipeline_version_run_id>
clarifai pr cancel  <pipeline_version_run_id>
clarifai pr resume  <pipeline_version_run_id>

Flag-based usage (still supported)

clarifai pipelinerun pause --pipeline_version_run_id=...
clarifai pipelinerun cancel --pipeline_version_run_id=...
clarifai pipelinerun resume --pipeline_version_run_id=...

Full form (when config is not available)

clarifai pipelinerun pause <pipeline_version_run_id> \
  --user_id=... \
  --app_id=... \
  --pipeline_id=... \
  --pipeline_version_id=...

Parameter resolution logic

The following parameters are optional if config-lock.yaml is present (generated via clarifai pipeline upload):

• --user_id
• --app_id
• --pipeline_id
• --pipeline_version_id

Resolution order:

1. If pipeline_version_run_id is provided as a positional argument, use it.
2. Otherwise, fall back to --pipeline_version_run_id.

If config-lock.yaml exists:

1. Load it as a PipelineVersion object.
2. Extract user_id, app_id, pipeline_id, and pipeline_version_id from it.

If config-lock.yaml is missing or invalid, all parameters must be explicitly provided via CLI flags.

CLI help / UX expectations

The --help output for each command should clearly document when the operation is allowed, based on the current orchestration status:

• Pause

  • Allowed only when the pipeline run is in Queued or Running state

• Cancel

  • Allowed when the pipeline run is not already in a terminal state

• Resume

  • Allowed only when the pipeline run is in Paused state

The CLI does not need to proactively validate the current status before issuing the request; allowed transitions should be documented in help text and enforced by backend responses.

How to implement

Dependencies

• Use clarifai-grpc >= 11.11.3

  • This version introduces JOB_PAUSED orchestration status.

API usage

Use PatchPipelineVersionRunsRequest to update the PipelineVersionRun status.

Pause

Set orchestration status to JOB_PAUSED.

&api.PatchPipelineVersionRunsRequest{
  UserAppId: userAppId,
  PipelineId: ...,
  PipelineVersionId: ...,
  PipelineVersionRuns: []*api.PipelineVersionRun{
    {
      Id: ...,
      OrchestrationStatus: &api.OrchestrationStatus{
        Status: &status.Status{Code: status.StatusCode_JOB_PAUSED},
      },
    },
  },
}

Cancel

Set orchestration status to:

status.StatusCode_JOB_CANCELLED

Resume

Set orchestration status to:

status.StatusCode_JOB_RUNNING

Acceptance criteria

• clarifai pipelinerun pause|cancel|resume commands are available
• clarifai pr alias works identically
• pipeline_version_run_id works as a positional argument and as a flag
• Parameters are correctly inferred from config-lock.yaml when present
• CLI --help clearly documents allowed state transitions
• Uses PatchPipelineVersionRunsRequest with clarifai-grpc >= 11.11.3