Inspect GitHub Codespace Logs Without Losing the Target

You will finish with a repeatable way to read a GitHub Codespace's logs, narrow selection to a repository or owner, and follow new output while diagnosing a running environment. The examples use GitHub CLI 2.87.3, the installed version checked for this guide.

Allow about ten minutes for a first check. You need the gh command, an authenticated GitHub CLI session with access to the Codespace, and the Codespace name or enough repository information to identify it. These commands inspect logs. They do not rebuild, stop, delete or edit a Codespace, and they do not need sudo.

1. Confirm the installed command

Check the executable and its version first. This is read-only and safe to run on any shell:

$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)

Your path and release date can differ. The relevant check is that the command is the GitHub CLI you expect. Confirm the subcommand's local contract as well:

$ gh codespace logs --help
Access codespace logs

USAGE
  gh codespace logs [flags]

FLAGS
  -c, --codespace string    Name of the codespace
  -f, --follow              Tail and follow the logs
  -R, --repo string         Filter codespace selection by repository name (user/repo)
      --repo-owner string   Filter codespace selection by repository owner (username or org)

--help is useful when a machine has more than one gh installation on its PATH. Do not copy an option from a different GitHub CLI command: the logs command has a small, specific set of flags.

2. Check authentication without exposing a token

Codespace logs are remote data. Before debugging selection, check that the CLI has a usable account and host configuration:

$ gh auth status
github.com
  ✓ Logged in to github.com account YOUR_ACCOUNT
  - Active account: true
  - Git operations protocol: https
  - Token scopes: ...

The account name and scope lines depend on your setup. Never paste a token into this article's commands or into a support ticket. If authentication fails, repair it with your normal organisation-approved login process, then rerun gh auth status. Do not start by changing repository permissions or deleting credentials.

3. Select one Codespace explicitly

The safest troubleshooting command names the target directly. Replace the placeholder with the exact Codespace name shown by GitHub:

$ gh codespace logs --codespace CODESPACE_NAME

Short option syntax is equivalent:

$ gh codespace logs -c CODESPACE_NAME

The command writes the selected logs to your terminal and returns when the log request is complete. Do not treat a blank screen as proof that nothing happened: the Codespace may simply have no output for the period being returned. Check the exit status immediately if the result is unexpected:

$ printf 'exit status: %s\n' "$?"
exit status: 0

A zero status tells you that the command completed successfully. It does not prove that the log content explains your application problem. Read the first and last visible lines, then record the time of any error before rerunning the command.

4. Filter an ambiguous selection

If you do not have the exact name, use the repository filter to constrain Codespace selection. The value must be in user/repo form, not just a repository's short name:

$ gh codespace logs --repo EXAMPLE_OWNER/EXAMPLE_REPOSITORY

Use --repo-owner when the owner is the useful boundary:

$ gh codespace logs --repo-owner EXAMPLE_ORGANISATION

These flags filter selection; they are not alternate names for --codespace. If several Codespaces still match, stop and identify the target rather than picking the first plausible entry. If no Codespace matches, check spelling, owner, repository visibility and the active account. A filter cannot grant access that the account does not have.

For a reproducible incident record, prefer the explicit --codespace form once you have identified the name:

$ gh codespace logs --codespace CODESPACE_NAME > codespace.log
$ test -s codespace.log && echo 'log file is non-empty'
log file is non-empty

The redirection changes only your local working directory. Choose a new filename first, because > truncates an existing file before gh runs. If you accidentally chose the wrong destination, stop and check it before overwriting anything else. The remote Codespace is not changed by this redirection.

5. Follow live logs deliberately

Use --follow when you need to watch new log output while reproducing a failure:

$ gh codespace logs --codespace CODESPACE_NAME --follow

This is a long-running terminal command. Press Ctrl-C when you have captured enough output. Interrupting the local client stops the watch; it does not stop or delete the Codespace. If the terminal appears stuck after the incident, check whether --follow was left in a shell history command before assuming the network request has failed.

Do not leave a follow session running unattended when logs may contain source code, paths, user names or other sensitive data. Save only the lines needed for diagnosis, protect any local capture according to your team's policy, and remove it through the approved retention process when it is no longer required.

6. Separate selection errors from log errors

Work through failures in this order:

1. Run gh --version and gh codespace logs --help to confirm the binary and flags.
2. Run gh auth status to confirm the account and host.
3. Use --codespace with the exact name, avoiding ambiguous filters.
4. Add --repo or --repo-owner only when you need to narrow selection.
5. Add --follow only after one non-following request identifies the correct target.

This order prevents a common distraction: changing several variables at once and then not knowing whether the account, selector or log stream caused the result. If a request reports that the Codespace cannot be found, verify its name and visibility from an account that should have access. If the command reaches the target but the application still fails, the GitHub CLI has completed its part; investigate the log lines and the application separately.