> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primeintellect.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Inference deployments

> Commands and options for catalog models, training checkpoints, and dedicated endpoint lifecycle management.

These commands are available in Prime CLI 0.21.0 and later. [Deploy a dedicated endpoint](https://docs.primeintellect.ai/inference/dedicated-deployments.md) provides a walkthrough.

Deployment management uses the platform API and requires Model Factory permissions, `factory:read` for reads and `factory:write` for mutations. Model requests use the inference API and require **Inference** permission.

## Commands

| Command | Purpose |
| - | - |
| `prime inference catalog` | List deployable catalog model IDs and team cluster IDs. |
| `prime inference deploy <model-catalog-id>` | Create a dedicated deployment of a catalog model. |
| `prime inference deploy-checkpoint <run-id> --step <step>` | Deploy a saved checkpoint. |
| `prime train deploy <run-id> --step <step>` | Alias for `deploy-checkpoint`. |
| `prime inference deployments list` | List personal deployments, or team deployments with `--team`. In Prime CLI 0.21.0, `list` ignores the selected CLI team. |
| `prime inference deployments get <deployment-id>` | Read status, endpoint, and replica information. |
| `prime inference deployments scale <deployment-id> --replicas <count>` | Set a running deployment's desired replica count. |
| `prime inference deployments delete <deployment-id>` | Stop serving and release the deployment's GPUs. |

All deployment commands accept `--output json`, abbreviated `-o json`. The default is human-readable output. `prime train checkpoints <run-id> --status READY` lists saved checkpoints.

## Catalog and catalog deployment options

| Option | Applies to | Default and behavior |
| - | - | - |
| `--team`, `-t` | `catalog`, `deploy` | Selected CLI account context. An explicit team ID overrides it. |
| `--cluster` | `deploy` | Omitted. Prime chooses on-demand capacity. A cluster ID selects a team-owned cluster. |
| `--name`, `-n` | `deploy` | Generated name. Explicit names have at most 29 characters, use lowercase letters, digits, and dashes, and start and end with a letter or digit. |
| `--replicas`, `-r` | `deploy` | `1`. Accepts `1` through `4`, subject to available capacity and account limits. |
| `--wait`, `-w` | `deploy` | Off. Polls until `RUNNING` or a terminal state. |
| `--timeout` | `deploy` | `1800` seconds. Bounds `--wait`, with a minimum of `1`. |

The deployment argument is the catalog's `id`, not its `repo`, `slug`, or display name. `prime inference models` lists models for requests to shared inference. `prime inference catalog` lists configurations for dedicated deployments.

## Checkpoint deployment options

| Option | Default and behavior |
| - | - |
| `--step`, `-s` | Required nonnegative checkpoint step. No automatic latest-step selection. |
| `--team`, `-t` | The run's team. Does not inherit the selected CLI team. |
| `--wait`, `-w` | Off. Polls until `RUNNING` or a terminal state. |
| `--timeout` | `1800` seconds. Bounds `--wait`, with a minimum of `1`. |

Both checkpoint command names have these options. Neither accepts `--cluster`, `--name`, or `--replicas`. Placement defaults to the run's own team cluster when it still belongs to that team, and to on-demand capacity otherwise. The [deployment API](https://docs.primeintellect.ai/api-reference/inference-deployments.md#deploy-a-checkpoint) also accepts explicit on-demand placement and initial replica count.

## Lifecycle options

| Command | Option | Behavior |
| - | - | - |
| `deployments list` | `--team`, `-t` | In Prime CLI 0.21.0, omitting it lists personal deployments even if `prime config set-team-id` selected a team; pass a team ID to list that team's deployments. |
| `deployments scale` | `--replicas`, `-r` | Required desired count, `1` through `32`. The deployment's `maxReplicas` can impose a lower cap. |
| `deployments delete` | `--yes`, `-y` | Skips the deletion confirmation. |

`get`, `scale`, and `delete` address the deployment by ID and have no `--team` option. The API checks access to the deployment's account.

## JSON output

`catalog -o json` returns `{models: [...], clusters: [...]}`. `deployments list -o json` returns `{data: [...]}`. Other deployment commands return a deployment object.

| Field | Meaning |
| - | - |
| `id` | Deployment ID used by lifecycle commands. |
| `deploymentName` | Human-readable deployment name. |
| `status`, `statusPhase`, `errorMessage` | Lifecycle status, optional startup phase, and optional error details. |
| `servedModelAlias` | Exact model identifier for requests to this deployment. |
| `endpointUrl` | OpenAI-compatible base URL. Null until `RUNNING`. |
| `checkpoint` | `{runId, step}` for a checkpoint deployment, otherwise null. |
| `isOnDemand` | Whether the deployment uses on-demand capacity. |
| `replicas`, `gpusPerReplica`, `maxReplicas` | Desired count, GPUs for each replica, and current replica cap. These fields can be null. |
| `scaleState` | State of a replica change. The desired count does not assert that workers are ready. |
| `createdAt`, `dashboardUrl` | Creation timestamp and dashboard link. |

In JSON mode, deployment wait progress and errors go to stderr. Stdout contains the JSON result when one is returned.

## Wait and deletion behavior

`--wait` exits successfully when the deployment is `RUNNING`. A terminal deployment state, timeout, or repeated polling failure exits with code `1`. A timeout or lost API connection does not delete the deployment.

Scaling and deletion are asynchronous. A scale response acknowledges the desired count. Deletion returns the deployment in `TERMINATING` state while teardown proceeds. Once teardown removes the record, `get` can return not found.
