--- title: Using GitHub Codespaces with GitHub CLI shortTitle: GitHub CLI intro: 'You can work with {% data variables.product.prodname_github_codespaces %} directly from your command line by using `gh`, the {% data variables.product.product_name %} command line interface.' product: '{% data reusables.gated-features.codespaces %}' miniTocMaxHeadingLevel: 3 versions: fpt: '*' type: how_to topics: - Codespaces - CLI - Developer redirect_from: - /codespaces/developing-in-codespaces/using-codespaces-with-github-cli --- ## About {% data variables.product.prodname_cli %} {% data reusables.cli.about-cli %} For more information, see "[About {% data variables.product.prodname_cli %}](/github-cli/github-cli/about-github-cli)." You can work with {% data variables.product.prodname_codespaces %} in the {% data variables.product.prodname_cli %} to: - [About {% data variables.product.prodname_cli %}](#about--data-variablesproductprodname_cli-) - [Installing {% data variables.product.prodname_cli %}](#installing--data-variablesproductprodname_cli-) - [Using {% data variables.product.prodname_cli %}](#using--data-variablesproductprodname_cli-) - [`gh` commands for {% data variables.product.prodname_github_codespaces %}](#gh-commands-for--data-variablesproductprodname_github_codespaces-) - [List all of your codespaces](#list-all-of-your-codespaces) - [Create a new codespace](#create-a-new-codespace) - [Stop a codespace](#stop-a-codespace) - [Delete a codespace](#delete-a-codespace) - [SSH into a codespace](#ssh-into-a-codespace) - [Open a codespace in {% data variables.product.prodname_vscode %}](#open-a-codespace-in--data-variablesproductprodname_vscode-) - [Open a codespace in JupyterLab](#open-a-codespace-in-jupyterlab) - [Copy a file to/from a codespace](#copy-a-file-tofrom-a-codespace) - [Examples](#examples) - [Modify ports in a codespace](#modify-ports-in-a-codespace) - [Access codespace logs](#access-codespace-logs) ## Installing {% data variables.product.prodname_cli %} {% data reusables.cli.cli-installation %} ## Using {% data variables.product.prodname_cli %} If you have not already done so, run `gh auth login` to authenticate with your {% data variables.product.prodname_dotcom %} account. To use `gh` to work with {% data variables.product.prodname_codespaces %}, type `gh codespace ` or its alias `gh cs `. As an example of a series of commands you might use to work with {% data variables.product.prodname_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 {% data variables.product.prodname_github_codespaces %} The sections below give example commands for each of the available operations. For a complete reference of `gh` commands for {% data variables.product.prodname_github_codespaces %}, including details of all available options for each command, see the {% data variables.product.prodname_cli %} online help for "[gh codespace](https://cli.github.com/manual/gh_codespace)." Alternatively, use `gh codespace [...] --help` on the command line. {% note %} **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. {% endnote %} ### List all of your codespaces ```shell 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 ```shell gh codespace create -r owner/repository [-b branch] ``` For more information, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace)." ### Stop a codespace ```shell gh codespace stop -c codespace-name ``` For more information, see "[Deep dive into {% data variables.product.prodname_github_codespaces %}](/codespaces/getting-started/deep-dive#closing-or-stopping-your-codespace)." ### Delete a codespace ```shell gh codespace delete -c codespace-name ``` For more information, see "[Deleting a codespace](/codespaces/developing-in-codespaces/deleting-a-codespace)." ### SSH into a codespace To run commands on the remote codespace machine, from your terminal, you can SSH into the codespace. ```shell gh codespace ssh -c codespace-name ``` {% data variables.product.prodname_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](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)." ### Open a codespace in {% data variables.product.prodname_vscode %} ```shell gh codespace code -c codespace-name ``` For more information, see "[Using {% data variables.product.prodname_codespaces %} in {% data variables.product.prodname_vscode %}](/codespaces/developing-in-codespaces/using-codespaces-in-visual-studio-code)." ### Open a codespace in JupyterLab ```shell gh codespace jupyter -c codespace-name ``` ### Copy a file to/from a codespace ```shell 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/` * 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 {% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_codespace_cp). ### 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. ```shell gh codespace ports forward codespace-port-number:local-port-number -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. {% data reusables.codespaces.port-visibility-settings %} ```shell 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: ```shell gh codespace ports visibility 80:private 3000:public 3306:org -c codespace-name ``` For more information, see "[Forwarding ports in your codespace](/codespaces/developing-in-codespaces/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. ```shell gh codespace logs -c codespace-name ``` For more information about the creation log, see "[{% data variables.product.prodname_github_codespaces %} logs](/codespaces/troubleshooting/github-codespaces-logs#creation-logs)."