Stop the Right Codespace with gh codespace stop

gh codespace stop shuts down one running GitHub Codespace from a Linux shell, without deleting it or its files. Allow about five minutes for an ordinary user-owned Codespace, plus extra time if this machine has never authenticated with GitHub CLI before.

The command syntax is small, but target selection is what matters: stopping the wrong Codespace is disruptive, even though starting it again later is usually possible. The examples use GitHub CLI 2.87.3.

1. Check the installed command

Confirm the command is installed and inspect this version's options:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh codespace stop --help
Stop a running codespace

USAGE
  gh codespace stop [flags]

There is no force flag, no confirmation flag, and no option to delete data. The accepted options are --codespace, --org, --repo, --repo-owner and --user: do not borrow a flag from another gh command.

Checkpoint: if gh codespace stop --help does not show the option you need, stop here and check the installed CLI version and its manual rather than guessing at a replacement spelling.

2. List the Codespaces you can target

For a personal Codespace, list the available names first. This is read-only and gives you the repository and state to compare against your intended target:

$ gh codespace list --limit 30
NAME                 DISPLAY NAME       REPOSITORY        STATE
octo-codespace-123   web-fix             octo-org/web     Available
octo-codespace-456   test-shell          octo-org/api     Running

Columns and values depend on the account. Use the exact value in the NAME column with --codespace, never a display name, a repository name or a truncated terminal column. If the list runs longer than the limit, raise --limit and search the returned names rather than grabbing the first match.

An authentication or scope error here means refreshing GitHub CLI authentication through your normal account process; GitHub may report that the token needs the codespace scope. Never paste a token into a command or article, and never use sudo to repair a per-user GitHub login.

Checkpoint: write down the exact Codespace name, repository and current state. If it is not the Codespace you meant to stop, do not continue.

3. Stop a named personal Codespace

Once the target is confirmed, stop it by its exact name:

$ gh codespace stop --codespace octo-codespace-456
✓ Stopped codespace octo-codespace-456

The short form is -c. Swap in the value from your own listing:

$ gh codespace stop -c CODESPACE_NAME

A successful shell return means GitHub accepted the request without a CLI-side error; the exact success message can differ between releases. Verify the state instead of trusting a copied or partial name:

$ gh codespace view --codespace octo-codespace-456 --json name,state
{"name":"octo-codespace-456","state":"Shutdown"}

State names and JSON formatting come from the current CLI and service. The check that matters is that the named Codespace is no longer running. Still running? Wait briefly and query it again before starting another operation.

4. Stop an organisation-owned Codespace

Organisation selection is a separate administrative path. The local manual marks --org as admin-only, paired with --user to identify the member whose Codespace should stop:

$ gh codespace stop --org octo-org --user octocat --codespace octo-codespace-789
✓ Stopped codespace octo-codespace-789

Use this only when you are authorised to administer Codespaces billed to that organisation. The username is not a substitute for the organisation login: --org names the organisation, --user narrows the member, and a normal user-owned Codespace needs neither.

Establish the exact name first through the organisation-aware listing, if your account permits it:

$ gh codespace list --org octo-org --user octocat
NAME                 DISPLAY NAME       REPOSITORY        STATE
octo-codespace-789   incident-check     octo-org/service  Running

An administrator can still hit an API permission error if the token, host or account is wrong. Fix the account context first: elevated Linux privileges cannot grant GitHub organisation rights.

5. Filter by repository only when the name is unambiguous

The stop command can filter selection by repository with --repo, or by owner with --repo-owner:

$ gh codespace stop --repo octo-org/web
✓ Stopped codespace octo-codespace-123

Convenient when the repository maps to one obvious Codespace, but a poor choice when several Codespaces share that repository. The interface never promises a repository filter is unique, so list first and use --codespace whenever there is any ambiguity.

$ gh codespace stop --repo-owner octo-org --codespace octo-codespace-123

Combining a name with a filter gives you a second assertion about the target. If the two disagree, treat the error as useful information rather than removing the filter blindly.

Common traps

Warning: stopping a Codespace disrupts anyone using it. Warn collaborators before stopping a shared development environment, and keep unsaved work in the remote editor or terminal in mind: stopping is not deletion, but it is not a substitute for saving or committing changes either.

To undo the operational effect, start the Codespace again from the GitHub Codespaces interface or your account's usual start workflow. gh codespace stop has no undo flag of its own, and it never deletes the stopped environment.

Done means