runpod · promptless · Jul 10, 2026 · Jul 13, 2026 · Jul 30, 2026 · Sep 2, 2026
diff --git a/docs.json b/docs.json
@@ -423,6 +423,7 @@
               "runpodctl/reference/runpodctl-pod",
               "runpodctl/reference/runpodctl-serverless",
               "runpodctl/reference/runpodctl-template",
+              "runpodctl/reference/runpodctl-model",
               "runpodctl/reference/runpodctl-hub",
               "runpodctl/reference/runpodctl-network-volume",
               "runpodctl/reference/runpodctl-registry",

diff --git a/runpodctl/overview.mdx b/runpodctl/overview.mdx
@@ -1,12 +1,12 @@
 ---
 title: "Overview"
 sidebarTitle: "Overview"
 description: "Use Runpod CLI to manage Pods, Serverless endpoints, templates, and more from your local machine."
 ---

 import { PodsTooltip, PodTooltip } from "/snippets/tooltips.jsx";

 Runpod CLI is an [open source](https://github.com/runpod/runpodctl) command-line tool for managing your Runpod resources from your local machine. You can manage Pods, Serverless endpoints, templates, network volumes, and models, transfer files between your system and Runpod, diagnose issues, and view account information.

 ## Quick start

@@ -20,7 +20,7 @@
 runpodctl pod list                  # List your Pods
 ```

 ## Install Runpod CLI locally

 Every <PodTooltip /> you deploy comes preinstalled with `runpodctl` and a Pod-scoped API key. You can also install it on your local machine to manage resources remotely.

@@ -145,7 +145,7 @@
 runpodctl doctor
 ```

 This command guides you through first-time setup, including API key configuration and SSH key setup.

 Alternatively, you can manually configure your API key:

@@ -158,7 +158,7 @@
 saved apiKey into config file: /Users/runpod/.runpod/config.toml
 ```

 ### Step 3: Verify installation

 To verify that `runpodctl` installed successfully, run this command:

@@ -166,7 +166,7 @@
 runpodctl version
 ```

 You should see which version is installed:

 ```bash
 runpodctl v2.0
@@ -174,13 +174,14 @@

 ## Command groups

 Runpod CLI organizes commands into groups based on the resource type:

 | Command | Alias | Description |
 |---------|-------|-------------|
 | `runpodctl pod` | | Manage Pods (create, list, start, stop, delete) |
 | `runpodctl serverless` | `sls` | Manage Serverless endpoints |
 | `runpodctl template` | `tpl` | List, search, and manage templates |
+| `runpodctl model` | | Manage models in the model repository (add, list, remove) |
 | `runpodctl hub` | | Browse and deploy from the Runpod Hub |
 | `runpodctl network-volume` | `nv` | Manage network volumes |
 | `runpodctl registry` | `reg` | Manage container registry authentications |
@@ -192,7 +193,7 @@

 ## Help and reference

 Learn how to use Runpod CLI commands by browsing the CLI reference using the sidebar to the left, or by running the `help` command:

 ```bash
 runpodctl help
@@ -211,6 +212,6 @@
 runpodctl completion
 ```

 This command auto-detects your shell and adds the appropriate source command to your shell configuration file (`~/.bashrc` or `~/.zshrc`). The command is idempotent—running it again skips installation if completion is already configured.

 Restart your shell or source the configuration file for changes to take effect.
diff --git a/runpodctl/reference/runpodctl-config.mdx b/runpodctl/reference/runpodctl-config.mdx
@@ -1,9 +1,9 @@
 ---
 title: "config"
 sidebarTitle: "config"
 ---

 Configure the Runpod CLI with your API credentials and API URL to enable programmatic access to your Runpod resources.

 <RequestExample>
 ```bash Command
@@ -13,7 +13,7 @@

 ## Example

 Configure the CLI with your API key:

 ```bash
 runpodctl config --apiKey "your-api-key-here"
@@ -35,6 +35,22 @@
 The Runpod API endpoint URL. The default value should work for most users.
 </ResponseField>
 
+## Environment variables
+
+You can also configure the CLI using environment variables. When set, these take precedence over the corresponding values in your config file.
+
+<ResponseField name="RUNPOD_API_KEY" type="string">
+Your Runpod API key. Overrides the `apiKey` value in your config file.
+</ResponseField>
+
+<ResponseField name="RUNPOD_GRAPHQL_URL" type="string">
+The Runpod GraphQL API endpoint URL. Overrides the `apiUrl` value in your config file.
+</ResponseField>
+
+<ResponseField name="RUNPOD_API_URL" type="string">
+The Runpod REST API endpoint URL. Overrides the `restApiUrl` value in your config file.
+</ResponseField>
+
 ## Related commands
 
 - [`runpodctl doctor`](/runpodctl/reference/runpodctl-doctor)

diff --git a/runpodctl/reference/runpodctl-model.mdx b/runpodctl/reference/runpodctl-model.mdx
@@ -0,0 +1,151 @@
+---
+title: "model"
+sidebarTitle: "model"
+---
+
+Manage models in the Runpod model repository. Use these subcommands to upload model files, list your models, and remove models or individual model versions.
+
+<RequestExample>
+```bash Command
+runpodctl model <subcommand> [flags]
+```
+</RequestExample>
+
+## Subcommands
+
+### Add a model
+
+Add a model to the model repository. You can add a model in two ways: by uploading model files from your local machine, or by mirroring an existing Hugging Face model server-side.
+
+To upload model files from your local machine, point `--model-path` at the directory that contains them:
+
+```bash
+runpodctl model add --name "my-model" --owner "my-team" --model-path ./model
+```
+
+When you upload from a directory in a terminal, `runpodctl` shows a progress bar with upload progress and estimated time remaining, then prints the total model size once the upload finishes.
+
+If you reuse one local directory across model versions without this flag, a later upload can include a mix of old and new files. Add `--delete-my-model-files-after-upload` to remove exactly the files this run uploaded from `--model-path` once the model version hash is confirmed server-side. It never touches unrelated files, and it runs only on confirmed success, so a failed or timed-out upload leaves your files in place. This flag requires both `--model-path` and `--wait-for-hash`.
+
+```bash
+runpodctl model add --name "my-model" --owner "my-team" --model-path ./model --wait-for-hash --delete-my-model-files-after-upload
+```
+
+To mirror an existing Hugging Face model into the Runpod model repository, use `--huggingface-model` with the source model in `owner/repo` form. `--name` sets the destination model name in the Runpod repository, and `--owner` is optional when mirroring.
+
+The transfer runs server-side, so there is no local upload session, file upload, or progress bar. Runpod creates the new model version right away and transfers the files from Hugging Face in the background.
+
+Mirroring cannot be combined with the local-upload flags (`--model-path`, `--create-upload`, `--file-name`, `--file-size`, `--part-size`, `--content-type`, and `--wait-for-hash`). Uploading and mirroring are two separate ways to add a model.
+
+```bash
+runpodctl model add --name tiny-llm --huggingface-model arnir0/Tiny-LLM
+```
+
+#### Add flags
+
+<ResponseField name="--name" type="string">
+Model name.
+</ResponseField>
+
+<ResponseField name="--owner" type="string">
+Model owner namespace (a user or team owner ID).
+</ResponseField>
+
+<ResponseField name="--model-path" type="string">
+Directory containing the model files to upload.
+</ResponseField>
+
+<ResponseField name="--huggingface-model" type="string">
+Hugging Face model to mirror into the Runpod model repository, in `owner/repo` form. Cannot be combined with the local-upload flags (`--model-path`, `--create-upload`, `--file-name`, `--file-size`, `--part-size`, `--content-type`, and `--wait-for-hash`).
+</ResponseField>
+
+<ResponseField name="--wait-for-hash" type="bool" default="false">
+Wait for uploaded model files to finish hashing before the command returns. Requires `--model-path`. When hashing completes, `runpodctl` prints a message confirming the model is ready to deploy along with its model URL.
+</ResponseField>
+
+<ResponseField name="--hash-timeout" type="duration" default="30m0s">
+Maximum time to wait when `--wait-for-hash` is set. Set to `0` to wait indefinitely.
+</ResponseField>
+
+<ResponseField name="--delete-my-model-files-after-upload" type="bool" default="false">
+Delete the uploaded `--model-path` files after the model version hash is confirmed server-side. Only the files this run uploaded are deleted, including nested subdirectories, and only after the hash is confirmed. If hash confirmation times out or fails, no files are deleted.
+
+Requires both `--model-path` and `--wait-for-hash`. Both are validated before the upload begins, so the command fails immediately if either is missing.
+
+If a specific file cannot be deleted, the command exits non-zero and names that file, so there is no silent partial success. A stderr confirmation line prints once at least one file has been deleted. The `deletedModelFiles` (count) and `deletedModelFilesBytes` (bytes) fields are added to the JSON output only when `--verbose`, `-v` is set.
+</ResponseField>
+
+<ResponseField name="--verbose, -v" type="bool" default="false">
+Include the full upload details in the `--wait-for-hash` output. Without this flag, a compact summary is printed instead.
+</ResponseField>
+
+<Note>
+
+`runpodctl model add` also accepts lower-level flags for configuring uploads directly, such as `--content-type`, `--file-name`, `--file-size`, `--part-size`, `--metadata`, and `--model-status`. Run `runpodctl model add --help` to see the complete list.
+
+</Note>
+
+### List models
+
+List the models in your model repository:
+
+```bash
+runpodctl model list
+```
+
+#### List flags
+
+<ResponseField name="--name" type="string">
+Filter the results by model name.
+</ResponseField>
+
+<ResponseField name="--provider" type="string">
+Filter the results by provider.
+</ResponseField>
+
+### Remove a model
+
+Remove a model from the model repository:
+
+```bash
+runpodctl model remove --name "my-model" --owner "my-team"
+```
+
+To remove a single model version instead of the entire model, pass either `--hash` or `--version`. This marks that version as removed and leaves the rest of the model in place.
+
+```bash
+runpodctl model remove --name "my-model" --owner "my-team" --version "<version-uuid>"
+```
+
+<Warning>
+
+`runpodctl model remove` refuses to remove a model or version that a Serverless endpoint still references. Removing the whole model is refused if any version is referenced; removing a specific version with `--hash` or `--version` is refused only when that exact version is referenced. The command reports which endpoints block the removal, and nothing is deleted when a removal is refused.
+
+There is no override or force flag. A model or version in active use cannot be removed until you detach or replace it on the referencing endpoint. If the dependency check cannot complete, for example when the API is unreachable, the removal is also refused, because Runpod treats an unverifiable dependency check as unsafe.
+
+</Warning>
+
+To clear a blocked removal, detach or replace the model on the referencing endpoint, then retry the removal. Detach the model with `runpodctl serverless update <endpoint-id> --clear-models`, or replace it with `runpodctl serverless update <endpoint-id> --model-reference <model-reference-url>`. See the [Update an endpoint](/runpodctl/reference/runpodctl-serverless#update-an-endpoint) section for details. If the referencing endpoint is a GPU endpoint, this update currently fails until the pending fix ships; see the [limitation on `--model-reference` and `--clear-models`](/runpodctl/reference/runpodctl-serverless#update-flags).
+
+#### Remove flags
+
+<ResponseField name="--name" type="string">
+Model name.
+</ResponseField>
+
+<ResponseField name="--owner" type="string">
+Model owner.
+</ResponseField>
+
+<ResponseField name="--hash" type="string">
+Hash of the model version to remove. Cannot be combined with `--version`.
+</ResponseField>
+
+<ResponseField name="--version" type="string">
+UUID of the model version to remove. Cannot be combined with `--hash`.
+</ResponseField>
+
+## Related commands
+
+- [`runpodctl serverless`](/runpodctl/reference/runpodctl-serverless)
+- [`runpodctl config`](/runpodctl/reference/runpodctl-config)
diff --git a/runpodctl/reference/runpodctl-serverless.mdx b/runpodctl/reference/runpodctl-serverless.mdx
@@ -1,4 +1,4 @@
 ---
 title: "serverless"
 sidebarTitle: "serverless"
 ---
@@ -75,7 +75,7 @@
  --env MAX_TOKENS=4096
 ```

 When using `--hub-id`, GPU IDs and container disk size are automatically pulled from the Hub release config. You can override the GPU type with `--gpu-id`. Environment variables from the Hub release are included automatically, and you can override or add to them with `--env`.

 <Note>

@@ -165,6 +165,12 @@
 
 ```bash
 runpodctl serverless update <endpoint-id> --workers-max 5
+
+# Cache a model reference on the endpoint
+runpodctl serverless update <endpoint-id> --model-reference https://huggingface.co/<owner>/<model>:<revision>
+
+# Clear all model references from the endpoint
+runpodctl serverless update <endpoint-id> --clear-models
 ```
 
 #### Update flags
@@ -205,6 +211,24 @@
 Execution timeout in seconds. Jobs that exceed this duration are terminated.
 </ResponseField>
 
+Attaching model references caches the referenced models on the endpoint so workers start faster and cost less. See [Model caching](/serverless/endpoints/model-caching) for when and why to cache models.
+
+<ResponseField name="--model-reference" type="string">
+Model reference URL to cache on the endpoint, in the same form used by `serverless create` (a Hugging Face reference like `https://huggingface.co/<owner>/<model>:<revision>`). Repeatable: use multiple `--model-reference` flags to cache several models. Replaces the endpoint's existing model references. Cannot be combined with `--clear-models`.
+</ResponseField>
+
+<ResponseField name="--clear-models" type="bool">
+Remove all model references from the endpoint. Cannot be combined with `--model-reference`.
+</ResponseField>
+
+<Warning>
+
+Updating an existing endpoint's model references with `--model-reference` or `--clear-models` currently works only on CPU (non-GPU) endpoints. On a GPU endpoint, this update cannot preserve the endpoint's GPU configuration, so it is rejected and the endpoint is left unchanged. A fix is pending.
+
+This limitation applies only to the update path shown here. GPU endpoints can still attach model references when you create them with `serverless create --model-reference`, or through the console. See [Model caching](/serverless/endpoints/model-caching) for the caching flow that still works on GPU endpoints.
+
+</Warning>
+
 ### Delete an endpoint
 
 Delete an endpoint: