List and Inspect Codespace Ports with gh codespace ports

gh codespace ports shows every port a GitHub Codespace has exposed, in a human-readable table or as script-friendly JSON. Allow about ten minutes: the examples only list and inspect, they never forward a port or touch its visibility.

You need GitHub CLI installed, an authenticated account with access to at least one Codespace, and a shell.

1. Check the installed command

Start with a read-only version and help check. Neither needs elevated privileges:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh codespace ports --help
List ports in a codespace

This guide's executable reports GitHub CLI 2.87.3, and the installed gh-codespace-ports(1) manual is dated March 2026 and documents the same shape. Package versions and help text differ between machines, so keep this check near the start of any script or troubleshooting note.

$ command -v gh
/usr/bin/gh
$ gh auth status

Do not paste the authentication status, a token or other credential material into an issue or log. Missing authentication means running your normal gh auth login process, which changes local credential state and is deliberately not part of this read-only workflow.

2. List ports from the selected Codespace

With one obvious Codespace, the shortest command works on its own:

$ gh codespace ports

It lists ports for whichever Codespace GitHub CLI selects, with a label, the source port inside the Codespace, the visibility, and a browse URL when one exists. The exact rows depend on the account and what is currently running.

If selection is ambiguous, make it explicit with the name from gh codespace list:

$ gh codespace list
$ gh codespace ports --codespace CODESPACE_NAME

Swap in the exact value from the first command, quoted if it contains shell-significant characters. --codespace has the short form -c.

$ gh codespace ports --repo OWNER/REPOSITORY
$ gh codespace ports --repo-owner OWNER

--repo expects the user/repo form. These flags narrow which Codespace is selected; they do not filter the port rows themselves.

3. Request only the fields a script needs

For automation, ask for JSON rather than scraping aligned columns. The command documents four fields: browseUrl, label, sourcePort and visibility:

$ gh codespace ports --codespace CODESPACE_NAME \
    --json label,sourcePort,visibility,browseUrl
[
  {
    "label": "web",
    "sourcePort": 3000,
    "visibility": "private",
    "browseUrl": "https://..."
  }
]

The values and object count are Codespace-specific. A browse URL can be absent or vary with port state, so scripts should tolerate an empty value rather than assume every row is browsable. The source port lives inside the Codespace; it is not necessarily a local listening port on your workstation.

Add --jq for a small projection or condition, without changing anything remote:

$ gh codespace ports --codespace CODESPACE_NAME \
    --json label,sourcePort \
    --jq '.[] | "\(.label): \(.sourcePort)"'
web: 3000

That expression runs against the JSON result, not as a shell pipeline, so keep it inside single quotes unless you deliberately want shell expansion. For a bigger transformation, --template uses the Go template formatting documented by gh help formatting:

$ gh codespace ports --codespace CODESPACE_NAME \
    --json label,visibility \
    --template '{{range .}}{{.label}}: {{.visibility}}{{"\n"}}{{end}}'

4. Treat visibility as a security boundary

This command only reports the current state. Changing it is a different operation: gh codespace ports visibility changes visibility, and gh codespace ports forward forwards a port. Both carry their own security and connectivity consequences, so keep either out of a script that is meant to stay read-only.

Nothing in this guide needs undoing, since none of it changes Codespace state. If a port has already been changed through another command, use the visibility command's documented options and the intended previous value to restore it, then confirm with gh codespace ports --json label,visibility again.

Common traps

• No Codespace selected. List them first and pass an exact name with --codespace.
• Repository filter returns nothing. Check owner and repository spelling, and confirm your account can access the Codespace.
• Authentication fails. Check gh auth status and re-authenticate through the supported flow rather than putting a token in a command argument, shell history or script.
• A JSON field is rejected. Run gh codespace ports --help and compare the requested names against the local field list; they are case-sensitive.
• An empty array is not an error. It means no matching port rows at that moment, which is different from malformed JSON or a failed API request.

Do not use sudo for any of this. GitHub CLI needs your user authentication and network access, not root privileges, and running it as root can make credentials and configuration look missing because root may use a different CLI configuration directory.