Codespaces — Understanding GitHub CLI

GitHub Codespaces are cloud-hosted development environments. The gh codespace (or gh cs) command lets you create, manage, and connect to them from your terminal.

Creating a Codespace

# Interactive — prompts for repo, branch, machine type
gh codespace create
 
# Non-interactive
gh codespace create --repo cli/cli
gh codespace create --repo cli/cli --branch main
gh codespace create --repo cli/cli --machine largePremiumLinux
gh codespace create --repo cli/cli --idle-timeout 30m
gh codespace create --repo cli/cli --retention-period 720h
gh codespace create --repo cli/cli --devcontainer-path .devcontainer/devcontainer.json

Listing Codespaces

gh codespace list
 
# Filter by repo
gh codespace list --repo cli/cli
 
# Filter by organization
gh codespace list --org my-org
 
# JSON output
gh codespace list --json name,repository,state,machineName

Viewing Codespace Details

gh codespace view
 
# View a specific codespace
gh codespace view --codespace <codespace-name>
 
# JSON output
gh codespace view --json name,state,machineName,createdAt

Connecting via SSH

# Interactive — choose from your codespaces
gh codespace ssh
 
# Connect to a specific codespace
gh codespace ssh --codespace <codespace-name>
 
# Run a command without an interactive session
gh codespace ssh --codespace <name> -- ls -la

SSH Config Setup

# Add codespace SSH entries to your SSH config
gh codespace ssh --config

Opening in an Editor

# Open in VS Code (default)
gh codespace code
 
# Open a specific codespace
gh codespace code --codespace <name>
 
# Open in VS Code Insiders
gh codespace code --insiders
 
# Open in the browser-based editor
gh codespace code --web

Copying Files

# Local to codespace
gh codespace cp local-file.txt remote:~/project/
 
# Codespace to local
gh codespace cp remote:~/project/output.log ./
 
# Recursive copy
gh codespace cp -r ./local-dir remote:~/project/dir
 
# Specify codespace
gh codespace cp -c <codespace-name> file.txt remote:~/

Port Forwarding

Forward Ports

# Forward a single port
gh codespace ports forward 8080:8080
 
# Forward multiple ports
gh codespace ports forward 8080:8080 3000:3000

List Ports

gh codespace ports --codespace <name>

Change Port Visibility

gh codespace ports visibility 8080:public --codespace <name>
gh codespace ports visibility 8080:private --codespace <name>
gh codespace ports visibility 8080:org --codespace <name>

Viewing Logs

gh codespace logs
gh codespace logs --codespace <name>
 
# Follow logs in real time
gh codespace logs --follow

Running Jupyter

Launch JupyterLab connected to a codespace for interactive notebook development:

gh codespace jupyter
gh codespace jupyter --codespace <name>

This starts a Jupyter server inside the codespace and opens it in your browser.

Rebuilding a Codespace

gh codespace rebuild
gh codespace rebuild --codespace <name>
 
# Full rebuild (no cache)
gh codespace rebuild --full

Editing Codespace Settings

gh codespace edit --codespace <name> --machine largePremiumLinux
gh codespace edit --codespace <name> --display-name "My Dev Environment"

Stopping a Codespace

gh codespace stop
gh codespace stop --codespace <name>

Deleting a Codespace

gh codespace delete --codespace <name>
 
# Delete all codespaces for a repo
gh codespace delete --repo cli/cli --all
 
# Force delete (skip confirmation)
gh codespace delete --codespace <name> --force

Exercises

Create a codespace: gh codespace create --repo <your-repo>
List your codespaces: gh codespace list
SSH into it: gh codespace ssh
Stop it: gh codespace stop
Delete it: gh codespace delete