> ## Documentation Index
> Fetch the complete documentation index at: https://runpod-b18f5ded-mintlify-01a1b5c2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Use Runpod CLI to manage Pods, Serverless endpoints, templates, and more from your local machine. Review commands and usage guidance for the Runpod CLI.

export const PodTooltip = () => {
  return <Tooltip headline="Pod" tip="A dedicated GPU or CPU instance for containerized AI/ML workloads." cta="Learn more about Pods" href="/pods/overview">Pod</Tooltip>;
};

export const PodsTooltip = () => {
  return <Tooltip headline="Pods" tip="Dedicated GPU or CPU instances for containerized AI/ML workloads." cta="Learn more about Pods" href="/pods/overview">Pods</Tooltip>;
};

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

After installing and configuring `runpodctl`, you can start managing resources immediately:

```bash theme={null}
runpodctl doctor                    # First time setup (API key + SSH)
runpodctl gpu list                  # See available GPUs
runpodctl template search pytorch   # Find a template
runpodctl pod create --template-id runpod-torch-v21 --gpu-id "NVIDIA RTX 4090"
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.

### Step 1: Choose an installation method

Choose the installation method that matches your operating system.

<Tabs>
  <Tab title="Install script">
    The install script automatically detects your operating system and architecture:

    ```bash theme={null}
    bash <(wget -qO- cli.runpod.io)
    ```

    Or using curl:

    ```bash theme={null}
    bash <(curl -sL cli.runpod.io)
    ```

    The script installs the latest version to `/usr/local/bin` when run as root, or to `~/.local/bin` for non-root users. If you don't have root access, the script displays instructions for adding `runpodctl` to your PATH.
  </Tab>

  <Tab title="macOS">
    **Homebrew:**

    ```bash theme={null}
    brew install runpod/runpodctl/runpodctl
    ```

    **ARM (Apple Silicon):**

    ```bash theme={null}
    wget --quiet --show-progress https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-darwin-arm64 -O runpodctl && chmod +x runpodctl && sudo mv runpodctl /usr/local/bin/runpodctl
    ```

    **AMD (Intel):**

    ```bash theme={null}
    wget --quiet --show-progress https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-darwin-amd64 -O runpodctl && chmod +x runpodctl && sudo mv runpodctl /usr/local/bin/runpodctl
    ```
  </Tab>

  <Tab title="Linux">
    **AMD64 (x86\_64):**

    ```bash theme={null}
    wget --quiet --show-progress https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-linux-amd64 -O runpodctl && chmod +x runpodctl && sudo cp runpodctl /usr/bin/runpodctl
    ```

    **ARM64 (aarch64):**

    ```bash theme={null}
    wget --quiet --show-progress https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-linux-arm64 -O runpodctl && chmod +x runpodctl && sudo cp runpodctl /usr/bin/runpodctl
    ```

    **Non-root installation:**

    If you don't have root access, install to your user directory:

    ```bash theme={null}
    mkdir -p ~/.local/bin && wget --quiet --show-progress https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-linux-amd64 -O ~/.local/bin/runpodctl && chmod +x ~/.local/bin/runpodctl
    ```

    Then add `~/.local/bin` to your PATH by adding this line to your `~/.bashrc` or `~/.zshrc`:

    ```bash theme={null}
    export PATH="$HOME/.local/bin:$PATH"
    ```
  </Tab>

  <Tab title="Windows">
    ```bash theme={null}
    wget https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-windows-amd64.exe -O runpodctl.exe
    ```
  </Tab>

  <Tab title="Google Colab / Jupyter Notebook">
    ```bash theme={null}
    !wget --quiet --show-progress https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-linux-amd64 -O runpodctl
    !chmod +x runpodctl
    !cp runpodctl /usr/bin/runpodctl
    ```
  </Tab>

  <Tab title="conda / mamba / pixi">
    Pre-built binaries are available on [conda-forge](https://anaconda.org/conda-forge/runpodctl) for Linux (x86\_64, aarch64, ppc64le), macOS (x86\_64, arm64), and Windows (x86\_64).

    **conda:**

    ```bash theme={null}
    conda install conda-forge::runpodctl
    ```

    **mamba:**

    ```bash theme={null}
    mamba install conda-forge::runpodctl
    ```

    **pixi:**

    ```bash theme={null}
    pixi global install runpodctl
    ```
  </Tab>
</Tabs>

This installs `runpodctl` globally on your system, so you can run commands from any directory.

### Step 2: Configure your API key

Before you can use `runpodctl` locally, you must configure it with an [API key](/get-started/api-keys).

The easiest way to set up your API key and SSH configuration is with the `doctor` command:

```bash theme={null}
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:

```bash theme={null}
runpodctl config --apiKey YOUR_API_KEY
```

After running the command, you should see a confirmation message similar to this:

```text theme={null}
saved apiKey into config file: /Users/runpod/.runpod/config.toml
```

### Step 3: Verify installation

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

```bash theme={null}
runpodctl version
```

You should see which version is installed:

```bash theme={null}
runpodctl v2.0
```

## 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 hub`            |       | Browse and deploy from the Runpod Hub           |
| `runpodctl network-volume` | `nv`  | Manage network volumes                          |
| `runpodctl registry`       | `reg` | Manage container registry authentications       |
| `runpodctl gpu`            |       | List available GPUs                             |
| `runpodctl datacenter`     | `dc`  | List datacenters                                |
| `runpodctl billing`        |       | View billing history                            |
| `runpodctl user`           | `me`  | View account information                        |
| `runpodctl ssh`            |       | Manage SSH keys and get connection info         |

## 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 theme={null}
runpodctl help
```

Learn more about a particular command by running:

```bash theme={null}
runpodctl [command] --help
```

## Output format

Successful command output goes to standard output as JSON by default, which makes runpodctl scriptable and agent-friendly. Use the `--output` flag to switch to a human-readable table or YAML:

```bash theme={null}
runpodctl pod list                    # json (default)
runpodctl pod list --output=table     # table
runpodctl pod list --output=yaml      # yaml
```

`template search` and `hub search` emit `[]` on standard output when nothing matches, instead of a prose message, so a caller piping the output into a JSON parser gets a valid empty list on the no-match case.

### Error format

When a command fails, runpodctl writes a single flat JSON object to standard error and exits with a non-zero status. Branch on the `code` field, never on the message text:

```json theme={null}
{"error":"failed to get endpoint: endpoint not found","code":"not_found","status":404}
```

| Field    | Description                                                                                                                                                                                                                 |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `error`  | Human-readable message, unwrapped (never a nested JSON blob).                                                                                                                                                               |
| `code`   | Stable, lowercase identifier for the failure class. Present on every error from the resource commands.                                                                                                                      |
| `status` | HTTP status code. Only present when the failure came back from a REST call. Absent when the API answered `200` with an empty result (GraphQL reports missing resources this way), so branch on `code` rather than `status`. |

Codes runpodctl generates:

| Code                                                                                                | Meaning                                                                                                                                           |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `usage_error`                                                                                       | The invocation was wrong: unknown command or flag, bad or missing arguments, missing required flags. Usage text is printed after the JSON object. |
| `not_found`                                                                                         | The resource does not exist.                                                                                                                      |
| `bad_request`, `unauthorized`, `forbidden`, `conflict`, `rate_limited`, `server_error`, `api_error` | Derived from the REST status returned by the API.                                                                                                 |
| `graphql_error`                                                                                     | GraphQL returned an errors array (HTTP 200).                                                                                                      |
| `no_credentials`                                                                                    | No API key is configured. Run `runpodctl doctor` or set `RUNPOD_API_KEY`.                                                                         |
| `network_error`                                                                                     | The API could not be reached (DNS failure, connection refused, TLS error, timeout). This is the only code that means "transient, retry."          |
| `cli_error`                                                                                         | Any other local failure: validation, config, bad input, malformed `RUNPOD_API_URL`.                                                               |

The API can also return its own code, which is passed through in lowercase. Treat the list above as the set the CLI generates rather than an exhaustive one.

### Exit codes

Every documented resource command exits non-zero on failure, including `model`, `update`, `send`, and `receive` (which previously exited `0` on some failure paths). Do not rely on stdout being empty to detect failure. Check the exit code and parse the JSON error object on stderr.

A few legacy surfaces still print plain-text errors and do not carry a `code`:

* The legacy pod verbs (`get pod`, `create pod`, `remove pod`, `start pod`, `stop pod`, `create pods`, `remove pods`) and `get cloud` print `Error: <message>` via cobra and exit `1`.
* `exec` prints plain text and exits `1`.
* `project` prints to standard output and exits `0` on failure (tracked upstream).

Parsers should tolerate a non-JSON line on stderr from those commands, and should not rely on the exit code for `project` until the upstream fix lands.

### Environment variables

| Variable             | Default                         | Description                                                                                                          |
| -------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `RUNPOD_API_KEY`     | —                               | API key. Also settable via `runpodctl doctor` or `~/.runpod/config.toml`.                                            |
| `RUNPOD_API_URL`     | `https://rest.runpod.io/v1`     | REST control plane (config key `restApiUrl`).                                                                        |
| `RUNPOD_GRAPHQL_URL` | `https://api.runpod.io/graphql` | GraphQL control plane (config key `apiUrl`).                                                                         |
| `RUNPOD_INVOKE_URL`  | `https://api.runpod.ai/v2`      | Base URL used to build the Serverless invoke URLs reported by `serverless create/get/list` (config key `invokeUrl`). |

Invoke is a separate service from the control plane. Pointing `RUNPOD_API_URL` or `RUNPOD_GRAPHQL_URL` at a non-production host does not move the invoke URLs; override `RUNPOD_INVOKE_URL` explicitly when you need that.

## Shell completion

Enable tab completion for your shell to make working with `runpodctl` easier:

```bash theme={null}
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.