cli/cli

Codespace

Active contributors: Caleb Brose, Jose Garcia, JP Ungaretti

Purpose

gh codespace (gh cs) manages GitHub-hosted dev environments end to end: create, list, view, ssh in, forward ports, copy files, view logs, run Jupyter, edit configuration, rebuild, stop, delete. Unlike most commands that simply call the GitHub REST API, this tree includes a full SSH and port-forwarding client because Codespaces speak the Microsoft Dev Tunnels protocol on top of Live Share's RPC channel.

Directory layout

pkg/cmd/codespace/
  root.go                  # NewCmdCodespace
  create.go  list.go  view.go  delete.go  edit.go  stop.go  rebuild.go
  ssh.go                   # gh cs ssh: largest single file in this tree (~25 KB)
  ports.go                 # forward / list / merge ports
  code.go                  # gh cs code: open VS Code attached to a codespace
  jupyter.go               # gh cs jupyter
  logs.go
  codespace_selector.go    # interactive picker
  common.go                # shared helpers
  mock_api.go              # generated mock (~35 KB) used by tests

internal/codespaces/
  codespaces.go            # high-level orchestration (start, prep ports, ssh)
  ssh.go                   # ssh setup with tunneled TCP
  states.go                # codespace lifecycle states
  api/api.go               # REST + GraphQL client (~38 KB) targeting the Codespaces API
  connection/              # Dev Tunnels connection
  portforwarder/           # local port forwarding loop
  rpc/                     # Live Share RPC clients (codespace, fs, jupyter)

Key abstractions

Symbol	File	Role
`App`	`pkg/cmd/codespace/common.go`	The DI container for the codespace tree; holds the codespaces API client, IO, prompter, and feature flags.
`codespaces.API`	`internal/codespaces/api/api.go`	REST and GraphQL client for the codespaces service.
`connection.Manager`	`internal/codespaces/connection`	Establishes a Dev Tunnels connection.
`portforwarder.Forwarder`	`internal/codespaces/portforwarder`	Bridges local TCP listeners to remote Codespace ports.
`rpc` clients	`internal/codespaces/rpc/`	Live Share RPC for codespace control, filesystem ops, Jupyter.

How it works

gh cs ssh:

graph TD
    A[gh cs ssh] --> B[App resolves selected codespace]
    B --> C[api.GetCodespace start if needed]
    C --> D[connection.Manager opens Dev Tunnel]
    D --> E[portforwarder forwards SSH 2222]
    E --> F[exec local ssh client to forwarded port]
    F --> G[user lands inside codespace]

The codespace selector (codespace_selector.go) is reused by every subcommand: when the codespace is not specified by flag, it lists candidates and prompts.

gh cs ports forward 8080:8080 works similarly, but the local listener stays open until the user interrupts it.

Integration points

Owned by the @cli/codespaces team (see .github/CODEOWNERS).
Pulls in transitive dependencies: microsoft/dev-tunnels, gorilla/websocket, creack/pty, kballard/go-shellquote. These show up in reference/dependencies.md.
Tests rely on mock_api.go (a generated moq mock). Real network is never touched in unit tests.
Some commands (gh cs code) shell out to other CLIs (code, code-insiders) via cli/safeexec.

Entry points for modification

New subcommand: add pkg/cmd/codespace/<name>.go (this tree is flat, not nested per subcommand). Register in root.go.
New API call: extend internal/codespaces/api/api.go.
New RPC method: add a *rpc.Client method under internal/codespaces/rpc/<service>/. Regenerate any generated message types if the proto changes.

Key source files

File	Purpose
`pkg/cmd/codespace/root.go`	Subcommand registration.
`pkg/cmd/codespace/create.go`	Provisioning flow: machine type, branch, devcontainer choice.
`pkg/cmd/codespace/ssh.go`	SSH client wired to a forwarded port.
`pkg/cmd/codespace/ports.go`	Port forwarding and visibility management.
`pkg/cmd/codespace/codespace_selector.go`	Interactive codespace picker.
`internal/codespaces/codespaces.go`	High-level orchestration.
`internal/codespaces/api/api.go`	API client (~38 KB).
`internal/codespaces/portforwarder/portforwarder.go`	Local listener loop.
`internal/codespaces/rpc/codespace/codespace_host_service.v1.go`	Codespace control RPC.

Built by Factory AutoWiki from public repository content. It is a generated preview for codebase exploration, not source-maintained documentation.