Home / Alt manpages / gh-codespace-code(1)

  • gh-codespace-code(1)
  • User command
  • linux

Open the Right Codespace with gh codespace code

Three Codespaces with near-identical names, one wrong click, and you are editing the wrong branch. gh codespace code opens the one you mean, in desktop VS Code, VS Code for the web or Insiders. The examples match GitHub CLI 2.87.3, installed here on 23 September 2026, and take about ten minutes if gh is already installed and authenticated.

The route

Jump straight to the step you need, or tick off Done means at the end.

You need:

  • The GitHub CLI and a terminal.
  • Access to at least one Codespace.
  • Desktop mode: the local Visual Studio Code installation your system uses to handle the code command.
  • Web mode: a browser.

This guide opens or selects an existing Codespace. It does not create, rebuild, stop or delete one.

1. Check the command and sign in

Confirm the installed version and authentication before you troubleshoot 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 the CLI will use. If it says 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 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.

Checkpoint

Run gh codespace list. You should see the Codespaces available to the authenticated account, or a clear empty result if there are none. The name in this list is the value --codespace accepts.

2. Open a Codespace by selecting it

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

$ gh codespace code

Pick the intended Codespace from the interactive list. That is handy with several projects, but it is easy to choose the wrong similarly named environment. Read the repository and display details in the list before you confirm.

For a repeatable command, get the exact name from gh codespace list and 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. It may need to start or reconnect the Codespace first, so give the connection time to complete.

Checkpoint

The remote project appears in VS Code and the Codespaces connection indicator shows the selected environment.

Recovery

If the command returns to the shell without opening an editor, check that desktop Visual Studio Code is installed and that its command-line integration is available to the same user and PATH.

3. Filter the selection by repository

If you know the repository but not the Codespace name, narrow the selection with 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
  • Short option. -R.
  • Format. The value must be in user/repo form, not just the repository name.
  • Several matches. You still 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 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 would rather select than name it, 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 safely

First make the selection unambiguous and confirm 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 your GitHub access are fine. Investigate the local editor installation and command-line integration. If both modes fail, inspect the exact CLI error and the Codespace state shown by:

$ gh codespace view --codespace YOUR_CODESPACE_NAME

Warning

Do not answer a connection problem with gh codespace delete, stop or rebuild. Those are separate state-changing commands and can interrupt work or remove resources. Nothing in this guide is elevated: sudo is not required to select or open a Codespace.

Done means

  • Signed in. gh auth status identifies the intended GitHub account and host.
  • Name confirmed. gh codespace list supplied a current name or confirmed that no Codespaces are available.
  • Deliberate selection. The Codespace opened with an explicit name or a deliberate repository and owner filter.
  • Editor chosen. You picked desktop VS Code, --web or --insiders on purpose.
  • Nothing destroyed. No stop, rebuild or delete command was used while diagnosing the connection.