feat: expand runpodctl coverage with legacy-safe cli (#229)

* refactor(cli): restructure commands to noun-verb pattern and add resource groups

- rename module from runpodctl to runpod and binary to runpod
- change command structure from verb-noun to noun-verb pattern
- add new resource command groups: serverless, template, volume, registry
- add legacy command support for backward compatibility
- create internal api layer with rest client and resource methods
- add output formatting support (json/yaml/table)
- enhance ssh key management and commands
- update dependencies (cobra v1.8.1, viper v1.19.0)
- update documentation and add agents.md for ai tooling
- remove deprecated test files and consolidate version handling

* refactor(cli): rename volume to network-volume and remove table output

- rename volume command to network-volume with alias 'nv'
- remove table output format, keep only json and yaml
- hide deprecated project command
- update help text and command descriptions
- simplify api test responses to use direct arrays
- update all tests to reflect command rename and output changes

* feat(cli): add info commands and pod restart/reset operations

- add user command to show account info and balance (alias: me, account)
- add gpu command to list available gpu types
- add datacenter command to list datacenters (alias: dc)
- add billing command with subcommands for pods, serverless, network-volume
- add doctor command to diagnose and fix cli configuration issues
- add pod restart and reset commands
- refactor legacy commands to use actual commands with deprecation warnings
- improve config handling with explicit viper value setting
- update error messages to guide users to doctor command
- deprecate config command in favor of doctor
- update default ssh key name to RunPod-Key-Go
- add comprehensive e2e tests for all new commands
- update root help text with getting started instructions

* feat(cli): add shell completion with auto-detection

- add completion command that auto-detects shell (bash, zsh, fish, powershell)
- automatically install completion to appropriate config files
- disable default cobra completion command
- add hidden generate subcommand for advanced usage
- register completion and update commands in root
- update comment formatting in update command

* docs(cli): update help text and version to clarify runpod v2

- update root help text to mention runpod v2 (formerly runpodctl)
- update version template to include formerly runpodctl note
- update version command output to clarify migration from runpodctl

* feat(template): add search command and enhance list filtering

- add template search command to search by name or image
- add --type flag to filter templates (official, community, user)
- add --limit and --offset flags for pagination
- add --all flag to include user templates
- update list command with smart defaults (show all for official/user, limit for community)
- add graphql support for fetching official and community templates
- enhance gettemplate to try rest api first, fallback to graphql
- add template type constants and list options struct
- add comprehensive e2e tests for filtering and pagination

* feat(cli): expand pod, template, model, and ssh support

- add cpu pod creation with compute-type and gpu-type-id naming
- include ssh info and lifecycle fields in pod get output
- return template readme/env/ports on get and parse graphql ports
- promote model repo commands and add legacy get models mapping
- update gpu list output to gpu type id and expand e2e coverage

* feat(legacy): deprecate exec and restore legacy commands

keep exec as a hidden legacy command that points users to ssh, and restore missing legacy commands for cloud and multi-pod operations.

* fix(legacy): keep exec runnable and add project tests

preserve backward compatibility for legacy exec while pointing users to ssh. add project create/build test coverage and remove resolved issue notes.

* feat(pod): add global networking flag

add global-networking to pod create with validation and error hints, wire the rest request, add e2e coverage, and update the issue note.

* feat(pod): add public ip filter

add --public-ip for community cloud pods, wire supportPublicIp, add unit and e2e coverage, and document testing expectations.

* style(help): normalize help text

standardize command help text casing and plurals, and add unit + e2e checks to prevent regressions.

* fix(cli): keep runpodctl as primary binary

avoid breaking existing users by reverting the cli name to runpodctl.
align docs, tooling, and tests so install and update paths keep the same binary.

* test(e2e): cover legacy and cli entrypoints

add legacy command assertions and help coverage for remaining cli entrypoints.
include ssh, completion, and send/receive checks to catch regressions.

* ci(workflow): install govulncheck

install govulncheck in ci and call it directly to keep the build green.

* docs(agents): add cli pitfalls

document non-obvious pitfalls to avoid regressions in templates, legacy, and doctor.

* feat(pod): require template-id flag

use --template-id for pod creation to align with serverless and clarify intent.
update help text and e2e coverage accordingly.

* feat(cli): rename gpu id fields

rename gpu-type-id flag to gpu-id and normalize gpuTypeId output to gpuId.
align billing filters/grouping and update tests/docs; remove resolved docs/issues.

* feat(cli): refresh help and docs

simplify root help messaging and regenerate markdown docs for the new cli.
update pr template to match the new summary/testing guidance.

* refactor(module): align module path with repo

update go.mod module path to github.com/runpod/runpodctl and rewrite imports
to match; includes gofmt cleanup after the path change.

* chore(docs): untrack cli restructure justification

remove the cli restructure justification from the repo while keeping it locally.

Co-authored-by: Cursor <[email protected]>

* feat(pod): add --ssh flag to pod create

use graphql api for gpu pod creation to support startSsh field, which
controls whether ssh keys are injected into the pod. cpu pods fall back
to rest api since graphql requires gpuTypeId.

* fix(legacy): add missing model commands to legacy wrappers

create model and remove model were not registered in the legacy
command layer, causing flags like --name and --owner to be unknown.

* fix(model): remove unnecessary hash from model repo uploads

model repo uploads do not accept a hash, causing errors when specified.
also bumps go version to 1.25.7.

cherry-picked from #230.

* fix(cli): restore model upload timeout fallback and prevent legacy create panic

---------

Co-authored-by: Cursor <[email protected]>
Co-authored-by: max4c <[email protected]>

Author: 3 people

.github/workflows/ci.yml

@@ -12,11 +12,15 @@ jobs:
       # You can test your matrix by printing the current Go version
       - name: Display Go version
         run: go version
+      - name: Install govulncheck
+        run: |
+          go install golang.org/x/vuln/cmd/govulncheck@latest
+          echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
       - name: run vet
         run: go vet ./...
       - name: build all packages
         run: go build ./...
       - name: check for vulnerabilities
-        run: go tool govulncheck ./...
+        run: govulncheck ./...
       - name: Run tests
         run: go test -vet=off --cover ./...

AGENTS.md

@@ -0,0 +1,169 @@
+# AGENTS.md
+
+runpodctl cli: command-line tool for managing gpu pods, serverless endpoints, and developing serverless applications on runpod.
+
+## codebase structure
+
+```
+runpod/
+├── main.go                      # entry point, version injection
+├── cmd/                         # cli commands (cobra)
+│   ├── root.go                     # root command, config init
+│   ├── config.go                   # api key & ssh config
+│   ├── ssh.go                      # ssh key management & connections
+│   ├── pod/                        # pod commands
+│   │   ├── pod.go                     # parent command
+│   │   ├── list.go                    # list pods
+│   │   ├── get.go                     # get pod by id
+│   │   ├── create.go                  # create pod
+│   │   ├── update.go                  # update pod
+│   │   ├── start.go                   # start pod
+│   │   ├── stop.go                    # stop pod
+│   │   └── delete.go                  # delete pod
+│   ├── serverless/                 # serverless endpoint commands (alias: sls)
+│   │   ├── serverless.go              # parent command
+│   │   ├── list.go                    # list endpoints
+│   │   ├── get.go                     # get endpoint
+│   │   ├── create.go                  # create endpoint
+│   │   ├── update.go                  # update endpoint
+│   │   └── delete.go                  # delete endpoint
+│   ├── template/                   # template commands (alias: tpl)
+│   │   └── ...
+│   ├── volume/                     # network volume commands (alias: vol)
+│   │   └── ...
+│   ├── registry/                   # container registry auth (alias: reg)
+│   │   └── ...
+│   ├── transfer/                   # file transfer (croc)
+│   │   ├── transfer.go                # send/receive commands
+│   │   ├── croc.go                    # croc implementation
+│   │   └── rtt.go                     # relay rtt testing
+│   ├── project/                    # serverless project workflow
+│   │   ├── project.go                 # create, dev, deploy, build
+│   │   ├── functions.go               # project lifecycle logic
+│   │   └── starter_examples/          # template projects
+│   └── legacy/                     # deprecated command aliases
+│       └── legacy.go                  # backwards compatibility
+├── internal/
+│   ├── api/                        # api clients
+│   │   ├── client.go                  # rest client
+│   │   ├── pods.go                    # pod api methods
+│   │   ├── endpoints.go               # endpoint api methods
+│   │   ├── templates.go               # template api methods
+│   │   ├── volumes.go                 # volume api methods
+│   │   ├── registry.go                # registry auth methods
+│   │   └── graphql.go                 # graphql client (fallback)
+│   └── output/                     # output formatting
+│       └── output.go                  # json/yaml/table output
+├── docs/                           # generated documentation
+└── .goreleaser.yml                 # release configuration
+```
+
+## key technologies
+
+- **go 1.24** with modules
+- **cobra** — cli framework
+- **viper** — configuration management
+- **croc** — peer-to-peer file transfer (no api key required)
+- **rest api** — primary api (https://rest.runpod.io/v1)
+- **graphql** — fallback for features rest lacks
+
+## configuration
+
+- config file: `~/.runpod/config.toml`
+- api key via: `runpodctl config --apiKey=xxx`
+- environment override: `RUNPOD_API_KEY`, `RUNPOD_API_URL`
+
+## build commands
+
+```bash
+# local development build
+make local
+# output: bin/runpod
+
+# cross-platform release builds
+make release
+# outputs: bin/runpod-{os}-{arch}
+
+# run tests
+go test ./...
+```
+
+## command structure
+
+commands follow noun-verb pattern: `runpodctl <resource> <action>`
+
+| command | description |
+|---------|-------------|
+| `runpodctl pod list` | list all pods |
+| `runpodctl pod get <id>` | get pod by id |
+| `runpodctl pod create --image=<img>` | create a pod |
+| `runpodctl pod start <id>` | start a stopped pod |
+| `runpodctl pod stop <id>` | stop a running pod |
+| `runpodctl pod delete <id>` | delete a pod |
+| `runpodctl serverless list` | list endpoints (alias: sls) |
+| `runpodctl serverless get <id>` | get endpoint details |
+| `runpodctl template list` | list templates (alias: tpl) |
+| `runpodctl volume list` | list network volumes (alias: vol) |
+| `runpodctl registry list` | list registry auths (alias: reg) |
+| `runpodctl send <file>` | send file via croc |
+| `runpodctl receive <code>` | receive file via croc |
+| `runpodctl ssh list-keys` | list account ssh keys |
+| `runpodctl ssh connect <pod>` | show ssh connect command |
+| `runpodctl project create` | create serverless project |
+| `runpodctl project dev` | start dev session |
+| `runpodctl project deploy` | deploy as endpoint |
+| `runpodctl config --apiKey=xxx` | configure api key |
+
+## output format
+
+default output is json (for agents). use `--output=table` for human-readable format.
+
+```bash
+runpodctl pod list                    # json output
+runpodctl pod list --output=table     # table output
+runpodctl pod list --output=yaml      # yaml output
+```
+
+## where to make changes
+
+| task | location |
+|------|----------|
+| add new rest api operation | `internal/api/` |
+| add new cli command | `cmd/<resource>/` |
+| modify pod commands | `cmd/pod/` |
+| modify serverless commands | `cmd/serverless/` |
+| add project template | `cmd/project/starter_examples/` |
+| change file transfer | `cmd/transfer/` |
+| update ssh logic | `cmd/ssh.go` |
+| modify build/release | `makefile`, `.goreleaser.yml` |
+
+## api layer pattern
+
+rest api operations in `internal/api/`:
+1. define request/response structs
+2. call appropriate http method (Get, Post, Patch, Delete)
+3. parse json response
+4. return typed result or error
+
+graphql fallback in `internal/api/graphql.go` for features rest doesn't support (ssh keys, detailed pod info).
+
+## pitfalls (non-obvious)
+
+- templates are dual-source: official/community via graphql, user via rest; list/search merge results and apply search/pagination client-side; graphql failures are intentionally best-effort.
+- graphql template shapes are inconsistent: `ports` may be string or array, `env` is key/value pairs; normalize before output and only return `readme/env/ports` on `template get`.
+- `doctor` is the only mutating setup path (api key + ssh sync); onboarding/ssh changes must update both `cmd/doctor` and `internal/sshconnect` hints.
+- legacy commands must preserve stdout and behavior exactly; deprecation warnings go to stderr only (exec is the most common regression).
+- `cmd/project.go` is not wired into the cli; the hidden `project` command is created in `cmd/root.go` and wraps `cmd/project/*`.
+- api accepts `gpuTypeIds` arrays, but the cli is intentionally singular (`--gpu-id`); multi-id fallback must be an explicit new flag.
+
+## important notes
+
+- **never start/stop servers** — user handles that
+- file transfer (`send`/`receive`) works without api key
+- version is injected at build time via `-ldflags`
+- config auto-migrates from `~/.runpod.yaml` to `~/.runpod/config.toml`
+- ssh keys are auto-generated and synced to account on `config` command
+- all text output is lowercase and concise
+- default output format is json for agent consumption
+- always add unit + e2e tests for new behavior
+- e2e tests must clean up resources they create (use `t.Cleanup`)

CLAUDE.md

@@ -0,0 +1 @@
+See [AGENTS.md](./AGENTS.md) for project documentation.