Inventory Codespaces with gh codespace list

Before you delete, stop or script anything, gh codespace list tells you what you actually own. This guide shows you how to see the Codespaces on your authenticated GitHub account, narrow the list to a repository, and emit selected fields for a script. The examples match GitHub CLI 2.87.3, installed here on Linux, and take about ten minutes.

You need the gh package, network access to GitHub, and an authenticated account with permission to see the Codespaces you are querying.

This command only lists resources. It does not stop, delete, rebuild or edit a Codespace, and the examples do not need sudo. Organisation-wide queries are a separate administrative case: only use them when your GitHub account is an organisation administrator.

1. Check the installed command

Confirm the binary and version before relying on an option in a script. It is an ordinary read-only check:

$ command -v gh
/usr/bin/gh
$ gh version
gh version 2.87.3 (2026-02-23)
$ gh codespace list --help

The help output should show the command as gh codespace list [flags], with a default limit of 30. It also lists the JSON fields this installed release supports. If your version differs, read its help again before copying these examples into automation.

Checkpoint: gh is the binary you expect, and the command accepts the flags used below.

2. Check authentication without changing anything

Confirm which GitHub account the CLI is using before you list your own Codespaces:

$ gh auth status

If this says you are not logged in, authenticate through your normal GitHub CLI process before continuing. Do not paste a token into a shell command or save one in a script. A successful check does not guarantee access to every repository or organisation, because GitHub still applies the account's permissions to the list request.

3. List your Codespaces

Run the default query:

$ gh codespace list

The result is a human-readable table whose rows and values depend on your account. An empty result means no Codespaces were returned for the authenticated user. It is not a prompt to create one. The default maximum is 30 entries.

Raise or lower that ceiling explicitly when the number of results matters:

$ gh codespace list --limit 10

--limit controls how many entries the command lists. It does not filter by state, and it does not mean ten Codespaces will be created or selected for another action.

4. Narrow the list to a repository

Use the repository's full owner/name form to inspect one project:

$ gh codespace list --repo OWNER/REPOSITORY

Replace both placeholders, for example octo-org/sample-app. Keep the slash, and quote the value if it comes from a shell variable:

$ repo='OWNER/REPOSITORY'
$ gh codespace list --repo "$repo" --limit 50

Tip: if this returns nothing, check the spelling, the repository owner and your permissions before changing the limit. A larger limit cannot reveal a Codespace the account cannot see.

5. Request stable JSON for scripts

Table output suits a person but is awkward to parse. Ask for only the fields the script needs:

$ gh codespace list \
    --repo OWNER/REPOSITORY \
    --limit 50 \
    --json name,state,repository

The installed command documents fields including name, state, repository, owner, machineName, createdAt, lastUsedAt, gitStatus, displayName and vscsTarget. Ask for the smallest useful set. That makes downstream checks easier to review and stops a script quietly depending on an incidental field.

For a compact report, pipe the JSON through the command's jq filter:

$ gh codespace list \
    --json name,state \
    --jq '.[] | [.name, .state] | @tsv'
NAME<TAB>Available

The final line is illustrative: the name and state come from your account, and @tsv emits a literal tab. If no Codespaces exist, the filter emits no rows.

Warning: treat the output as data, not as a list of shell commands to run. A Codespace name or display value is not automatically safe to interpolate into another command.

Checkpoint: use --json when a program consumes the result, and --jq only for a deliberate projection of that JSON. Keep the original JSON while diagnosing a surprising result.

6. Query an organisation as an administrator

Organisation administrators can list all Codespaces billed to an organisation:

$ gh codespace list --org ORG_LOGIN

Replace ORG_LOGIN with the organisation login, not a display name. This is an administrative inventory and may expose other users' resources. Confirm the organisation, account and intended output before redirecting it to a file or sharing it.

To list Codespaces for one user within that organisation, add --user:

$ gh codespace list --org ORG_LOGIN --user GITHUB_USERNAME

--user is documented as being used with --org. Do not combine these organisation options with --web: browser mode is mutually exclusive with both --org and --user.

7. Open the web list instead

If you want GitHub's web interface rather than terminal output, use:

$ gh codespace list --web

This asks the CLI to list Codespaces in a browser. It is an interactive hand-off, not machine-readable output, and it cannot be used with --org or --user. If the browser does not open, use the terminal command and check authentication and the system's URL handler.

Common traps

Warning: listing is non-destructive, but the output can still be sensitive. Codespace names, repositories, owners and recent-use information may reveal project activity, so keep unfiltered output out of public logs. If you redirected data to a local file while troubleshooting, review and remove that file under your normal data-handling policy once you no longer need it.

Done means