Skip to content

docs: Document runpodctl template registry auth and port label flags #774

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lavanya-gunreddi merged 4 commits into from
Aug 7, 2026
Merged

docs: Document runpodctl template registry auth and port label flags #774

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
27008f7
Document runpodctl template registry auth and port label flags
promptless[bot] Jun 24, 2026
9bd95a8
docs(template): note port labels shown in template get output
promptless[bot] Jul 1, 2026
10ce502
docs: clarify --port-labels comma limitation for runpodctl template
promptless[bot] Jul 13, 2026
9ce0701
Merge branch 'main' into promptless/template-registry-auth-port-labels
lavanya-gunreddi Aug 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 30 additions & 1 deletion runpodctl/reference/runpodctl-template.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ Number of results to skip for pagination.

### Get template details

Get detailed information about a specific template, including README, environment variables, and exposed ports:
Get detailed information about a specific template, including README, environment variables, and exposed ports (with their labels):

@promptless promptless Bot Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR #297 makes GetTemplate backfill portsConfig from GraphQL so template get now echoes port labels; updated the "Get template details" description to mention labels are shown. The backfill lives in internal/api/templates.go.

Source: runpod/runpodctl#297


```bash
runpodctl template get <template-id>
Expand All @@ -110,6 +110,12 @@ runpodctl template create --name "my-template" --image "runpod/pytorch:2.8.0-py3

# Create a Serverless template
runpodctl template create --name "my-serverless-template" --image "my-image:latest" --serverless

# Create a template that pulls from a private registry
runpodctl template create --name "private-gpu" --image "registry.example.com/team/image:tag" --registry-auth-id <registry-auth-id>

# Create a template with labeled ports
runpodctl template create --name "dev" --image "my-image:latest" --ports "22/tcp,8888/http" --port-labels "22=ssh,8888=jupyter lab"
```

<Note>
Expand Down Expand Up @@ -144,6 +150,14 @@ Volume mount path.
Comma-separated list of ports to expose (e.g., `8888/http,22/tcp`).
</ResponseField>

<ResponseField name="--port-labels" type="string">

@promptless promptless Bot Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documented the new --port-labels create flag from cmd/template/create.go and cmd/template/port_labels.go, which accept either port=name pairs or a JSON object and require --ports (the code returns "--port-labels requires --ports when creating a template" and validates each label against --ports).

Source: runpod/runpodctl#290

Display names for the ports the template exposes, shown next to each port in the Runpod console. Provide comma-separated `port=name` pairs (e.g., `22=ssh,8888=jupyter lab`) or a JSON object (e.g., `{"22":"ssh","8888":"jupyter lab"}`). This flag requires `--ports`, and every labeled port must also appear in `--ports`. The pair form splits on commas, so use the JSON form for any label name that contains a comma.

@promptless promptless Bot Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documented the comma limitation from parsePortLabels in cmd/template/port_labels.go: the port=name pair form splits on , (via strings.Split), so a label name containing a comma must use the JSON form. The flag help text in cmd/template/create.go states the same ("or json when a name contains a comma").

Source: https://github.com/runpod/runpodctl/blob/main/cmd/template/port_labels.go

</ResponseField>

<ResponseField name="--registry-auth-id" type="string">
ID of the container registry authentication used to pull the image from a private registry. Find the ID with [`runpodctl registry list`](/runpodctl/reference/runpodctl-registry).

@promptless promptless Bot Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documented the new --registry-auth-id create flag; the flag help text in cmd/template/create.go is "container registry auth id (from 'runpodctl registry list')", which is why the description links to the registry reference page.

Source: runpod/runpodctl#290

</ResponseField>

<ResponseField name="--env" type="string">
Environment variables as a JSON object (e.g., `'{"KEY":"value"}'`).
</ResponseField>
Expand All @@ -169,7 +183,14 @@ Template README content.
Update an existing template:

```bash
# Rename a template
runpodctl template update <template-id> --name "new-name"

# Attach registry credentials
runpodctl template update <template-id> --registry-auth-id <registry-auth-id>

# Update port labels (or pass "" to clear them)
runpodctl template update <template-id> --port-labels "22=ssh,8888=jupyter lab"
```

#### Update flags
Expand All @@ -186,6 +207,14 @@ New Docker image name.
New comma-separated list of ports.
</ResponseField>

<ResponseField name="--port-labels" type="string">
New display names for the template's exposed ports, as `port=name` pairs or a JSON object. Pass an empty value (`--port-labels ""`) to remove all port labels.

@promptless promptless Bot Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documented the --port-labels clear-on-update behavior; cmd/template/update.go flag help is "new port labels as port=name pairs or json; pass an empty value to clear" and runUpdate parses an empty value into an empty label set.

Source: runpod/runpodctl#290

</ResponseField>

<ResponseField name="--registry-auth-id" type="string">
New container registry authentication ID for pulling private images. Pass an empty value (`--registry-auth-id ""`) to detach registry credentials from the template.

@promptless promptless Bot Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documented the --registry-auth-id detach-on-update behavior; cmd/template/update.go flag help is "new container registry auth id; pass an empty value to clear" and runUpdate sends an empty ContainerRegistryAuthID when the flag is set to "".

Source: runpod/runpodctl#290

</ResponseField>

<ResponseField name="--env" type="string">
New environment variables as a JSON object.
</ResponseField>
Expand Down
Loading