Rename or Resize a Codespace with gh codespace edit

gh codespace edit changes a Codespace's display name or its machine type without touching the code inside it. A rename takes seconds; a machine change can interrupt a running session, so budget about fifteen minutes and pick your moment. The examples below use the installed GitHub CLI 2.87.3.

You need an authenticated gh installation, access to the target Codespace, and a shell. Every command here changes a remote Codespaces setting, but none of them need sudo.

1. Check the installed command

Read the local help before you pick a flag. This is read-only:

$ gh version
gh version 2.87.3 (2026-02-23)
$ gh codespace edit --help
Edit a codespace

The installed command accepts these controls:

Checkpoint: the command has no positional Codespace argument. Skip -c and gh picks from the available Codespaces instead of treating your first bare word as a name.

2. Find the permanent Codespace name

Run the list command to see the permanent name, repository and state. That permanent name, not the friendly display name, is what --codespace needs:

$ gh codespace list
NAME                              DISPLAY NAME       REPOSITORY       STATE
PERMANENT-CODESPACE-NAME          Old project name   OWNER/REPO       Available

Your own rows will differ. Filter by repository when the list runs long:

$ gh codespace list --repo OWNER/REPO
NAME                              DISPLAY NAME       REPOSITORY       STATE
PERMANENT-CODESPACE-NAME          Old project name   OWNER/REPO       Available

Copy the exact value from the NAME column, never a display name with spaces in it. An authentication error here means fixing gh authentication first, not typing a token into the command.

3. Inspect the current details

Before you touch anything, record the current state and machine name. That gives you a fallback if the rename or resize goes wrong:

$ gh codespace view --codespace PERMANENT-CODESPACE-NAME
Name: PERMANENT-CODESPACE-NAME
State: Available
Repository: OWNER/REPO
Machine type: CURRENT-MACHINE-NAME

Fields and formatting shift with the installed CLI and Codespace state. For values a script can parse, ask for JSON instead:

$ gh codespace view --codespace PERMANENT-CODESPACE-NAME --json name,displayName,machineName,state
{"name":"PERMANENT-CODESPACE-NAME","displayName":"Old project name","machineName":"CURRENT-MACHINE-NAME","state":"Available"}

Treat that sample as a shape, not a value to paste: keep the real machine name and state from your own result.

4. Rename without touching the machine

A display name only labels the Codespace in lists and clients. GitHub caps it at 48 characters including spaces, so quote it as one shell argument:

$ gh codespace edit \
    --codespace PERMANENT-CODESPACE-NAME \
    --display-name 'API review - staging'

Confirm the change:

$ gh codespace view --codespace PERMANENT-CODESPACE-NAME --json name,displayName
{"name":"PERMANENT-CODESPACE-NAME","displayName":"API review - staging"}

This changes only the label, never the permanent name your other commands rely on. Undo it by running the same command with the old display name:

$ gh codespace edit \
    --codespace PERMANENT-CODESPACE-NAME \
    --display-name 'Old project name'

5. Find a real machine type

A machine value is not a size you make up, such as large. It has to be a name GitHub actually offers for that Codespace, and the lookup is read-only:

$ gh api /user/codespaces/PERMANENT-CODESPACE-NAME/machines
[{"name":"standardLinux32gb","display_name":"..."}]

Use the exact name field for the machine you want. The choices depend on the Codespace, the account and what GitHub currently offers, so do not borrow a name from another repository or a marketing page.

Checkpoint: note both the current and replacement machine names before you touch anything. If the two machines have different storage capacity, GitHub stops the active Codespace automatically while the change is applied. If storage stays the same, the change waits for the next restart and nothing is stopped for you.

6. Change the machine type deliberately

This is a service-affecting action: performance changes, and billing may too. Save your work, warn anyone sharing the Codespace, and keep the old machine name handy for recovery:

$ gh codespace edit \
    --codespace PERMANENT-CODESPACE-NAME \
    --machine AVAILABLE-MACHINE-NAME

Leaving out --codespace can prompt you to pick one interactively, so keep supplying the permanent name explicitly. Check the result once it settles:

$ gh codespace view --codespace PERMANENT-CODESPACE-NAME --json name,machineName,state
{"name":"PERMANENT-CODESPACE-NAME","machineName":"AVAILABLE-MACHINE-NAME","state":"Available"}

Still transitioning? Wait and check again. Do not fire off a second edit while the first is still in progress.

7. Recover from a wrong machine choice

There is no local undo file for a Codespace edit. Recovery means picking the previous machine type again, provided it is still on offer:

$ gh api /user/codespaces/PERMANENT-CODESPACE-NAME/machines
$ gh codespace edit \
    --codespace PERMANENT-CODESPACE-NAME \
    --machine PREVIOUS-MACHINE-NAME
$ gh codespace view --codespace PERMANENT-CODESPACE-NAME --json machineName,state

If that machine has vanished from the list, compare the current options rather than guessing. A bad edit is never a reason to delete and recreate the Codespace: deletion is a separate, destructive command and it is outside this guide.

Done means