Open the Right GitHub Codespace with gh codespace code

You will finish with a repeatable way to open a GitHub Codespace in desktop Visual Studio Code, VS Code for the web, or Visual Studio Code Insiders. The examples match GitHub CLI 2.87.3, installed here on 23 September 2026. Allow about ten minutes if gh is already installed and authenticated.

You need the GitHub CLI, access to at least one Codespace, and a terminal. Desktop mode also needs the local Visual Studio Code installation that your system uses to handle the code command. Web mode needs a browser. This guide opens or selects an existing Codespace; it does not create, rebuild, stop or delete one.

1. Check the local command and sign in

Confirm the installed version and authentication before troubleshooting Codespaces:

$ gh --version
$ gh auth status

The first command should report gh version 2.87.3 on the system used for this guide. The second should report the account and host that the CLI will use. If it reports that you are not logged in, authenticate with your organisation's approved method:

$ gh auth login

Follow the prompts and do not paste a token into a command line that another user could read from shell history. Authentication is an account change, so stop at the prompt if you are unsure which GitHub host or account to select.

2. Open a Codespace by selecting it

With no selector, the command displays a list for you to choose from:

$ gh codespace code

Choose the intended Codespace from the interactive list. This is convenient when you have several projects, but it is easy to select the wrong similarly named environment. Read the repository and display details in the list before confirming.

For a repeatable command, obtain the exact name with gh codespace list, then pass it explicitly:

$ gh codespace code --codespace YOUR_CODESPACE_NAME

Replace YOUR_CODESPACE_NAME with the real name, without angle brackets. A successful command hands the selected Codespace to desktop Visual Studio Code. The command may need to start or reconnect the Codespace as part of opening it, so allow the connection time to complete.

3. Filter the selection by repository

If you know the repository but not the Codespace name, constrain the selection. Use the complete owner and repository name:

$ gh codespace code --repo YOUR_GITHUB_OWNER/YOUR_REPOSITORY

For example:

$ gh codespace code --repo octo-org/example-repo

The short option is -R. The value must be in user/repo form, not just the repository name. If the repository has several Codespaces, you still need to choose the correct one unless you also give --codespace.

You can filter by owner when that is the useful boundary:

$ gh codespace code --repo-owner YOUR_GITHUB_OWNER

These options filter Codespace selection. They do not create a Codespace and they do not change repository permissions. An organisation-owned Codespace may still be unavailable if the authenticated account lacks access.

4. Choose web VS Code or Insiders

Use the web editor explicitly when you are on a machine without desktop VS Code, or when you want the browser-based environment:

$ gh codespace code --web --codespace YOUR_CODESPACE_NAME

--web changes the editor destination, not the Codespace. The browser must be signed in to an account that can access it. If you prefer selection rather than a name, combine it with a repository filter:

$ gh codespace code --web --repo YOUR_GITHUB_OWNER/YOUR_REPOSITORY

For the preview build of desktop Visual Studio Code, use:

$ gh codespace code --insiders --codespace YOUR_CODESPACE_NAME

--insiders selects Visual Studio Code Insiders. It does not install Insiders, convert an existing installation, or affect the remote files. If that editor is missing or not registered for Codespaces, use ordinary desktop mode or --web.

5. Diagnose a failed open without changing the Codespace

First make the selection unambiguous and confirm that the name still exists:

$ gh codespace list
$ gh codespace code --codespace YOUR_CODESPACE_NAME

If the list is empty or the CLI reports an authentication problem, rerun gh auth status and check the account and GitHub host. If the Codespace belongs to an organisation, verify access with the organisation owner rather than trying random repository names.

If desktop mode fails but web mode opens the same environment, the remote Codespace and GitHub access are working. Investigate the local editor installation and command-line integration. Conversely, if both modes fail, inspect the exact CLI error and the Codespace state shown by:

$ gh codespace view --codespace YOUR_CODESPACE_NAME

Do not respond to a connection problem by running gh codespace delete, stop or rebuild. Those are separate state-changing commands and can interrupt work or remove resources. This guide contains no elevated commands: sudo is not required for selecting or opening a Codespace.