About GitHub CLI
GitHub CLI is an open source tool for using GitHub from your computer's command line. When you're working from the command line, you can use the GitHub CLI to save time and avoid switching context. For more information, see About GitHub CLI.
You can work with GitHub Codespaces in the GitHub CLI to:
- List all of your codespaces
- Create a new codespace
- View details of a codespace
- Stop a codespace
- Delete a codespace
- Rename a codespace
- Rebuild a codespace
- SSH into a codespace
- Open a codespace in Visual Studio Code
- Open a codespace in JupyterLab
- Copy a file to/from a codespace
- Modify ports in a codespace
- Access codespace logs
- Access remote resources
- Change the machine type of a codespace
Installing GitHub CLI
For installation instructions for GitHub CLI, see the GitHub CLI repository.
Using GitHub CLI
If you have not already done so, run gh auth login to authenticate with your GitHub account.
To use gh to work with GitHub Codespaces, type gh codespace SUBCOMMAND or its alias gh cs SUBCOMMAND.
As an example of a series of commands you might use to work with GitHub Codespaces, you could:
- List your current codespaces, to check whether you have a codespace for a particular repository:
gh codespace list - Create a new codespace for the required repository branch:
gh codespace create -r github/docs -b main - SSH into the new codespace:
gh codespace ssh -c octocat-literate-space-parakeet-7gwrqp9q9jcx4vq - Forward a port to your local machine:
gh codespace ports forward 8000:8000 -c octocat-literate-space-parakeet-7gwrqp9q9jcx4vq
gh commands for GitHub Codespaces
The sections below give example commands for each of the available operations.
For a complete reference of gh commands for GitHub Codespaces, including details of all available options for each command, see the GitHub CLI online help for gh codespace. Alternatively, on the command line, use gh codespace --help for general help or gh codespace SUBCOMMAND --help for help with a specific subcommand.
Note
The -c CODESPACE_NAME flag, used with many commands, is optional. If you omit it a list of codespaces is displayed for you to choose from.
List all of your codespaces
gh codespace list
The list includes the unique name of each codespace, which you can use in other gh codespace commands.
An asterisk at the end of the branch name for a codespace indicates that there are uncommitted or unpushed changes in that codespace.
Create a new codespace
gh codespace create -r OWNER/REPO_NAME [-b BRANCH]
For more information, see Creating a codespace for a repository.
View details of a codespace
gh codespace view
After running this command you are prompted to choose one of your existing codespaces. The following information is then displayed:
- Name of the codespace