Skip to main content

Using GitHub Codespaces with GitHub CLI

You can work with GitHub Codespaces directly from your command line by using gh, the GitHub command line interface.

GitHub Codespaces は、GitHub Team または GitHub Enterprise Cloud を使用する Organization で利用できます。 GitHub Free および GitHub Pro プランの個人ユーザーも、GitHub Codespaces を制限付きのベータ リリースとして利用できます。 詳細については、「GitHub's products」を参照してください。

About GitHub CLI

GitHub CLI は、コンピューターのコマンド ラインから GitHub を使用するためのオープン ソース ツールです。 コマンドラインから作業しているときは、GitHub CLI を使用して時間を節約し、コンテキストの切り替えを回避できます。 For more information, see "About GitHub CLI."

You can work with GitHub Codespaces in the GitHub CLI to:

Installing GitHub CLI

GitHub CLI のインストール手順については、GitHub CLI リポジトリを参照してください。

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 <COMMAND> or its alias gh cs <COMMAND>.

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 mona-github-docs-v4qxrv7rfwv9w
  • Forward a port to your local machine:
    gh codespace ports forward 8000:8000 -c mona-github-docs-v4qxrv7rfwv9w

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, use gh codespace [<SUBCOMMAND>...] --help on the command line.

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.

Create a new codespace

gh codespace create -r OWNER/REPO_NAME [-b BRANCH]

For more information, see "Creating a codespace."

Stop a codespace

gh codespace stop -c CODESPACE-NAME

For more information, see "Deep dive into GitHub Codespaces."

Delete a codespace

gh codespace delete -c CODESPACE-NAME

For more information, see "Deleting a codespace."

SSH into a codespace

To run commands on the remote codespace machine, from your terminal, you can SSH into the codespace.

gh codespace ssh -c CODESPACE-NAME

GitHub Codespaces copies your GitHub SSH keys into the codespace on creation for a seamless authentication experience. You may be asked to enter the passphrase for your SSH key, after which you will get a command prompt from the remote codespace machine.

If you don't have any SSH keys, follow the instructions in "Generating a new SSH key and adding it to the ssh-agent."

Open a codespace in Visual Studio Code

gh codespace code -c CODESPACE-NAME

For more information, see "Using GitHub Codespaces in Visual Studio Code."

Open a codespace in JupyterLab

gh codespace jupyter -c CODESPACE-NAME

Copy a file to/from a codespace

gh codespace cp [-r] SOURCE(S) DESTINATION

Use the prefix remote: on a file or directory name to indicate that it's on the codespace. As with the UNIX cp command, the first argument specifies the source and the last specifies the destination. If the destination is a directory, you can specify multiple sources. Use the -r (recursive) flag if any of the sources is a directory.

The location of files and directories on the codespace is relative to the home directory of the remote user.

Examples

  • Copy a file from the local machine to the $HOME directory of a codespace:

    gh codespace cp myfile.txt remote:

  • Copy a file to the directory in which a repository is checked out in a codespace:

    gh codespace cp myfile.txt remote:/workspaces/<REPOSITORY-NAME>

  • Copy a file from a codespace to the current directory on the local machine:

    gh codespace cp remote:myfile.txt .

  • Copy three local files to the $HOME/temp directory of a codespace:

    gh codespace cp a1.txt a2.txt a3.txt remote:temp

  • Copy three files from a codespace to the current working directory on the local machine:

    gh codespace cp remote:a1.txt remote:a2.txt remote:a3.txt .

  • Copy a local directory into the $HOME directory of a codespace:

    gh codespace cp -r mydir remote:

  • Copy a directory from a codespace to the local machine, changing the directory name:

    gh codespace cp -r remote:mydir mydir-localcopy

For more information about the gh codespace cp command, including additional flags you can use, see the GitHub CLI manual.

Modify ports in a codespace

You can forward a port on a codespace to a local port. The port remains forwarded as long as the process is running. To stop forwarding the port, press Control+C.

gh codespace ports forward CODESPACE-PORT_NAME:LOCAL-PORT-NAME -c CODESPACE-NAME

To see details of forwarded ports enter gh codespace ports and then choose a codespace.

You can set the visibility of a forwarded port. 3 種類の可視性の設定があります。

  • private - 自分にのみ表示されます。 これはポートを転送するときの既定の設定です。
  • org - リポジトリを所有する組織のメンバーに表示されます。
  • public - URL とポート番号を知っているすべてのユーザーに表示されます。
gh codespace ports visibility CODESPACE-PORT:private|org|public -c CODESPACE-NAME

You can set the visibility for multiple ports with one command. For example:

gh codespace ports visibility 80:private 3000:public 3306:org -c CODESPACE-NAME

For more information, see "Forwarding ports in your codespace."

Access codespace logs

You can see the creation log for a codespace. After entering this command you will be asked to enter the passphrase for your SSH key.

gh codespace logs -c CODESPACE-NAME

For more information about the creation log, see "GitHub Codespaces logs."

Access remote resources

You can use the GitHub CLI extension to create a bridge between a codespace and your local machine, so that the codespace can access any remote resource that is accessible from your machine. For more information on using the extension, see "Using GitHub CLI to access remote resources."

Note: The GitHub CLI extension is currently in beta and subject to change.

Change the machine type of a codespace

gh codespace edit -m machine-type-name

For more information, see the "GitHub CLI" tab of "Changing the machine type for your codespace."