Inspect a GitHub Codespace with gh codespace view

gh codespace view tells you exactly which Codespace you are looking at before you stop, rebuild or delete the wrong one. It only looks: it will not start, stop, rebuild, edit or delete anything. These examples use GitHub CLI 2.87.3, installed locally on 23 September 2026, and take about five minutes if you are already signed in.

Before you start

You need the GitHub CLI installed and an account that can see the Codespace. The command uses your normal GitHub CLI authentication, so no root access is required and adding sudo would not help. Check the client version and authentication before debugging selection:

gh --version
gh auth status

The first command should report a recent gh release. The second should show an account with access to the relevant repository. If authentication is missing or expired, fix that with your normal gh auth login process, then return here.

Checkpoint: You are ready when gh auth status succeeds and you know either the Codespace name or its repository in OWNER/REPOSITORY form.

1. Select a Codespace interactively

With no selector, the command presents Codespaces available to you so you can choose one. The short alias gh cs view is equivalent to the full command.

gh codespace view

This is useful when you do not remember the exact name. It is also the most likely place to make a wrong choice if you have several similarly named Codespaces. Read the repository and display name before continuing. Do not infer that the first entry is the active one.

2. Select by name or repository

Use --codespace when you know the Codespace name:

gh codespace view --codespace CODESPACE_NAME

Replace CODESPACE_NAME with the exact name shown by GitHub. If several Codespaces could match your task, narrow the selection by repository instead:

gh codespace view --repo OWNER/REPOSITORY

You can filter by owner separately, which is useful when repository names are repeated across accounts or organisations:

gh codespace view --repo REPOSITORY --repo-owner OWNER_OR_ORG

These selectors choose what to view; they do not alter the Codespace. If a command still offers multiple choices, stop and verify the repository rather than selecting by position.

Checkpoint: The selected result must identify the repository and Codespace you intended. If it does not, stop here and repeat the command with an explicit name or owner.

3. Ask for only the fields you need

For a compact human-readable check, request the display name, machine type, and state:

gh codespace view \
  --codespace CODESPACE_NAME \
  --json displayName,machineDisplayName,state

The result is JSON containing the requested fields. Field names are case-sensitive as shown by the command help. Useful fields include repository, machineName, machineDisplayName, state, createdAt, lastUsedAt, idleTimeoutMinutes, retentionExpiresAt, and retentionPeriodDays.

To see the complete field list supported by this installed version, omit the value after --json:

gh codespace view --json

That is a discovery command, not a stable data contract. When you write a script, name the small set of fields it actually consumes. This reduces noisy output and makes a later client upgrade easier to review.

4. Shape the output for a script

Use --jq to extract or reshape JSON with a jq expression. For example, this prints a compact status line from the fields requested by the command:

gh codespace view \
  --codespace CODESPACE_NAME \
  --json displayName,state,machineName \
  --jq '\"\(.displayName): \(.state) on \(.machineName)\"'

Keep the expression quoted so the shell passes its punctuation to gh. If another tool needs machine-readable data, prefer the JSON output itself rather than parsing a table intended for people. A missing or renamed field can then be detected as a data problem instead of silently becoming the wrong text.

For Go-template formatting, use --template. This example prints two fields on separate lines:

gh codespace view \
  --codespace CODESPACE_NAME \
  --json displayName,state \
  --template '{{.displayName}}\n{{.state}}\n'

Templates and jq filters apply to JSON output selected by --json. If you are unsure about their syntax, run gh help formatting and test against a known Codespace before putting the command in automation.

Common traps and recovery

No result or an error: check authentication, repository visibility, and the exact owner spelling. A local shell typo is easier to fix than a permissions diagnosis, so quote values containing unusual characters.
Unexpected Codespace: stop and rerun with --codespace or both repository filters. Do not follow a subsequent stop, rebuild, or delete command until the identity is confirmed.
Empty or surprising fields: request the field explicitly and inspect the raw JSON. A value such as a retention date describes metadata returned by GitHub at that time; it is not a promise that a Codespace will remain usable indefinitely.
Confusing display and machine names: displayName and machineDisplayName are different fields. Include name as well when recording an identifier for later commands.
Automation breaks after an upgrade: compare gh --version, then rerun gh codespace view --json to confirm the available fields. Treat a failed jq or template expression as a signal to review the field contract.

Safety boundary: Every example in this guide is observational. Commands such as gh codespace stop, gh codespace rebuild, and gh codespace delete change remote state and are outside this workflow. Before using any of them, confirm the exact Codespace name and read that command's help. A view operation cannot undo a change made by another command.

Done means

Version and auth checked. gh --version and gh auth status both came back clean.
Right Codespace selected. You picked it by name or by repository, not by guessing the first entry in a list.
Details inspected. Repository, state and machine came back through explicit --json fields.
Output shape decided. You know whether the next step needs raw JSON, a --jq filter or a --template.
Nothing touched. The Codespace has not been started, stopped, rebuilt or deleted.