PIPE-1113 PIPE-1114: Add CLI support for pause, cancel, resume, and monitor Pipeline Runs

[Copilot]

Why

• Enable pipeline run lifecycle management directly from CLI without requiring Python code
• Support pausing long-running pipelines for resource optimization
• Provide cancel/resume operations for workflow control
• Allow monitoring existing pipeline runs to track status and view logs in real-time

How

• New CLI commands (clarifai/cli/pipeline_run.py):

  • clarifai pipelinerun (alias pr) with subcommands: pause, cancel, resume, monitor
  • Accepts pipeline_version_run_id as positional arg or explicit flag
  • Auto-loads user_id, app_id, pipeline_id, pipeline_version_id from config-lock.yaml when present
  • Helper functions extract shared logic for config loading, validation, and pipeline instantiation
  • monitor command polls status and logs with configurable --timeout and --monitor_interval options

• Pipeline client method (clarifai/client/pipeline.py):

  • patch_pipeline_version_run() uses PatchPipelineVersionRunsRequest
  • Sets orchestration status: JOB_PAUSED (pause), JOB_CANCELLED (cancel), JOB_RUNNING (resume)
  • Imports status_pb2 from clarifai_grpc.grpc.api.status for consistency with codebase patterns
  • Enhanced logging includes all identifiers (user_id, app_id, pipeline_id, pipeline_version_id, pipeline_version_run_id) for better traceability

• Dependencies:

  • Updated clarifai-grpc>=11.11.3 for JOB_PAUSED status code support

# Minimal usage with config-lock.yaml present
clarifai pr pause <run_id>
clarifai pr resume <run_id>
clarifai pr monitor <run_id>

# Explicit parameters
clarifai pipelinerun cancel <run_id> \
  --user_id=USER \
  --app_id=APP \
  --pipeline_id=PIPELINE \
  --pipeline_version_id=VERSION

# Monitor with custom options
clarifai pr monitor <run_id> \
  --timeout=7200 \
  --monitor_interval=5 \
  --log_file=/path/to/logs.txt

Tests

• Comprehensive test suite covering positional/flag arguments, config loading, and error handling
• All commands mock Pipeline client to avoid external dependencies
• 13 tests total: 8 for pause/cancel/resume + 5 for monitor command

Notes

• Help text documents allowed state transitions per operation
• Context validation ensures authentication before API calls
• Uses consistent import patterns with existing codebase (e.g., model_runner.py)
• Success log messages include complete context for debugging and observability
• monitor command works identically to clarifai pipeline run --monitor flag behavior

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Feature: CLI support to pause, cancel, and resume Pipeline Runs</issue_title>
<issue_description>## 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</issue_description>

<agent_instructions>Ensure consistency with existing CLI, Client and other packages / modules code structure</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Feature: CLI support to pause, cancel, and resume Pipeline Runs #880

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[nitinbhojwani]

@copilot status_pb2 should be imported from clarifai_grpc.grpc.api.status similar to status_code_pb2

[Copilot]

Fixed in 1d6f78b. Changed to import status_pb2 from clarifai_grpc.grpc.api.status at the module level, consistent with the pattern used in model_runner.py and other parts of the codebase.

[nitinbhojwani]

@copilot also add a monitor command i.e. clarifai pipelinerun monitor <pipeline_version_run_id>

It should work exactly similar to how --monitor flag works in clarifai pipeline run ... --monitor where the current status and logs are polled.

Similar to pause:

• user_id, app_id, pipeline_id, pipeline_version_id should be loaded from config-lock.yaml and user can also provide them.

• Resolve pipeline_version_run_id from positional or flag

[Copilot]

Added in 2aa20e9. The monitor command works exactly like clarifai pipeline run --monitor:

• Accepts pipeline_version_run_id as positional arg or --pipeline_version_run_id flag
• Loads user_id, app_id, pipeline_id, pipeline_version_id from config-lock.yaml or CLI flags
• Supports --timeout and --monitor_interval options (defaults: 3600s and 10s)
• Supports --log_file option to write logs to a file
• Polls current status and displays logs in real-time

Usage: clarifai pr monitor <pipeline_version_run_id>