Inspect Codespace Ports as Human-Readable or JSON Data

You will use gh codespace ports to see the ports exposed by a GitHub Codespace, select a particular Codespace when more than one is available, and turn the result into script-friendly JSON. Allow about ten minutes. You need GitHub CLI installed, an authenticated account with access to at least one Codespace, and a shell. The examples only list and inspect ports. They do not forward a port or change its visibility.

1. Check the installed command

Start with a read-only version and help check. These commands do not need elevated privileges:

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

The executable used for this guide reports GitHub CLI 2.87.3. The installed gh-codespace-ports(1) manual is dated March 2026 and documents the same command shape. Package versions and help text can differ between machines, so keep this check near the start of scripts and troubleshooting notes.

Checkpoint: confirm that the command exists and that the account is authenticated before debugging port output:

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

Do not paste the authentication status, token or other credential material into an issue or log. If authentication is missing, use your normal gh auth login process. That changes local credential state, so it is intentionally not part of this read-only port workflow.

2. List ports from the selected Codespace

With one obvious Codespace, the shortest command is:

$ gh codespace ports

The command lists ports for a Codespace selected by GitHub CLI. The exact rows depend on the account and Codespaces currently available. The useful data includes a label, the source port inside the Codespace, the visibility, and a browse URL when one is available.

If selection is ambiguous, make it explicit. Use the Codespace name shown by gh codespace list:

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

Replace CODESPACE_NAME with the exact value returned by the first command. Keep the placeholder quoted if the name contains shell-significant characters. The long option --codespace has the short form -c.

Checkpoint: if you need to select by repository instead, use one of the documented filters:

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

--repo expects the user/repo form. These filters narrow Codespace selection; they do not filter the port rows themselves.

3. Request only the fields a script needs

For automation, request JSON rather than scraping aligned human-readable output. The installed command documents four JSON 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 number of objects are Codespace-specific. A browse URL can be absent or vary with the port state, so scripts should handle an empty value rather than assuming every row is browsable. The source port is the port inside the Codespace, not necessarily a local listening port on your workstation.

Use --jq when you need a small projection or condition. For example, this prints labels and source ports without changing anything:

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

The expression is applied to the JSON result. It is not a shell pipeline, so keep the expression inside single quotes unless you deliberately need shell expansion. For a larger transformation, --template uses the Go template formatting described 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

Read the visibility value before sharing a browse URL. A port marked public can be reachable by people who are not members of the repository or organisation. Do not copy a public URL into a ticket, chat room or build log unless that exposure is intended and approved.

This command only reports the current state. The related gh codespace ports visibility command changes visibility, and gh codespace ports forward forwards a port. Those are separate operations with security and connectivity consequences. Do not add either command to a diagnostic script that is meant to be read-only.

There is no undo action needed for the examples in this guide because they do not change Codespace state. If you have already changed a port through another command, use the visibility command's documented options and the intended previous value to restore it. Confirm the result by running gh codespace ports --json label,visibility again.

5. Diagnose the common failures

If the command says that no Codespace can be selected, list them first and pass an exact name with --codespace. If the repository filter returns nothing, check the owner and repository spelling and confirm that your account can access the Codespace.

If authentication fails, check gh auth status and the account or host it reports. Do not work around an access error by putting a token in a command argument, shell history or script. Re-authenticate through the supported GitHub CLI flow, then retry the list command.

If a JSON field is rejected, run gh codespace ports --help and compare the requested names with the local JSON field list. The documented names are case-sensitive. A successful command with an empty array means there were no matching port rows at that moment; it is different from malformed JSON or a failed API request.

Do not use sudo for any command here. The GitHub CLI needs your user authentication and network access, not root privileges. Running it as root can make credentials and configuration appear to be missing because root may use a different CLI configuration directory.