Add ports command for instances and nodes (#441)

* Add ports command for instances and nodes

* 📝 Add docstrings to `agent/list-instance-ports`

Docstrings generation was requested by @callen-bot.

The following files were modified:

* `pkg/cmd/cmd.go`
* `pkg/cmd/ports/ports.go`
* `pkg/cmd/util/externalnode.go`
* `pkg/cmd/util/util.go`

These files were ignored:
* `pkg/cmd/ports/ports_test.go`
* `pkg/cmd/util/externalnode_test.go`

These file types are not supported:
* `.agents/skills/brev-cli/SKILL.md`
* `.agents/skills/brev-cli/reference/commands.md`

* Address ports review feedback

* Label SSH ports as network ports

* Refine ports list command

* Show ports list in command help

* Avoid guessing missing destination ports

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: callen-bot

.agents/skills/brev-cli/SKILL.md

@@ -170,6 +170,10 @@ brev copy my-instance:/remote/file ./local-path/
 
 # Port forward
 brev port-forward my-instance -p 8080:8080
+
+# List Brev-managed HTTP and network ports for an instance or external node
+brev ports ls my-instance
+brev ports ls my-node --json
 ```
 
 ### Listing Instances and Nodes

.agents/skills/brev-cli/reference/commands.md

@@ -466,6 +466,51 @@ brev port-forward my-instance -p 8080:8080
 brev port-forward my-instance -p 3000:3000
 ```
 
+### brev ports ls
+List Brev-managed HTTP applications and raw network port mappings for a
+managed instance or registered compute node.
+
+```bash
+brev ports ls <instance-or-node> [flags]
+```
+
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output the port mappings as JSON |
+
+The table output includes endpoint, IP restrictions, public port, destination
+port, and protocol. HTTP applications also include their authorization policy.
+
+For managed instances, this command reads the Brev-managed network
+configuration. It does not synthesize the legacy secure-link or firewall rows
+shown by the Brev console, because those rows do not have real port IDs and
+cannot be used by port-management automation. If the instance is still
+provisioning or uses legacy network access, the command returns an error
+directing the user to the console.
+
+The JSON output is an array with the following stable fields:
+
+| Field | Meaning |
+|------|---------|
+| `port_id` | Unique port mapping ID used by automation |
+| `endpoint` | Public URL or `host:port` endpoint |
+| `public_port` | Externally addressable port |
+| `destination_port` | Port listening on the target machine |
+| `protocol` | `HTTP`, `HTTPS`, `SSH`, `TCP`, `UDP`, or `UNKNOWN` |
+| `allowed_sources` | Allowed IP addresses or CIDR blocks |
+| `authorized_emails` | Identities authorized for an HTTP application |
+| `allow_public_unauthenticated` | Whether an HTTP application is public |
+| `type` | `system`, `user`, `unspecified`, or `unknown` |
+
+**Examples:**
+```bash
+brev ports ls my-instance
+brev ports ls my-node
+brev ports ls my-instance --json
+```
+
 ## Organization Commands
 
 ### brev org ls

pkg/cmd/cmd.go

@@ -35,6 +35,7 @@ import (
 	"github.com/brevdev/brev-cli/pkg/cmd/open"
 	"github.com/brevdev/brev-cli/pkg/cmd/org"
 	"github.com/brevdev/brev-cli/pkg/cmd/portforward"
+	"github.com/brevdev/brev-cli/pkg/cmd/ports"
 	"github.com/brevdev/brev-cli/pkg/cmd/profile"
 	"github.com/brevdev/brev-cli/pkg/cmd/proxy"
 	"github.com/brevdev/brev-cli/pkg/cmd/redeem"
@@ -276,6 +277,7 @@ func createCmdTree(cmd *cobra.Command, t *terminal.Terminal, loginCmdStore *stor
 	cmd.AddCommand(invite.NewCmdInvite(t, loginCmdStore, noLoginCmdStore))
 	cmd.AddCommand(redeem.NewCmdRedeem(t, loginCmdStore, noLoginCmdStore))
 	cmd.AddCommand(portforward.NewCmdPortForwardSSH(loginCmdStore, t))
+	cmd.AddCommand(ports.NewCmdPorts(loginCmdStore))
 	cmd.AddCommand(login.NewCmdLogin(t, noLoginCmdStore, loginAuth))
 	cmd.AddCommand(logout.NewCmdLogout(loginAuth, noLoginCmdStore))
 	cmd.AddCommand(tasks.NewCmdTasks(t, noLoginCmdStore))