Home / Alt manpages / gh-org(1)

  • gh-org(1)
  • User command
  • linux

List Your GitHub Organisations with gh org

An empty result from gh org list is not always a broken login, it might just be an honest answer, and this guide shows how to tell the two apart. Allow about five minutes if gh is already installed and logged in. Every example here only reads account data: nothing creates, edits or removes an organisation.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Check the installed command and your login

The reference machine's gh binary reports GitHub CLI 2.87.3, while the Debian package database says gh 2.45.0-1ubuntu0.3+esm3. Binary and package metadata do not agree here, so check both when a version-sensitive result looks off:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ dpkg-query -W -f='${Package} ${Version}\n' gh
gh 2.45.0-1ubuntu0.3+esm3

Next, confirm an account is actually active. This check can cover more than one known GitHub host, so read the host name and account rather than assuming the first section is the one that matters:

$ gh auth status
github.com
  ✓ Logged in to github.com account YOUR_ACCOUNT

Wording and account details vary. Skip --show-token for routine checks, since it prints a credential in plain text. Status reports a problem? Repair the login with your normal GitHub CLI process before you go anywhere near organisation membership.

Checkpoint

You have identified the gh binary and an active account for the host you intend to query.

2. List the first set of organisations

Run it plain, no flags:

$ gh org list
ORGANISATION_NAME

The default cap is 30 organisations, and the heading and layout can shift between CLI versions. A successful command with zero rows is still a useful answer: the active account may simply belong to no organisation visible to it.

On the reference machine, a limit of one returned exactly one organisation:

$ gh org list --limit 1
foag-org

Your result will not match that name, and it should not: treat organisation names as account data, not as a value to copy into a script unchecked.

3. Raise the limit when the list looks truncated

gh org list makes no promise to show everything past the default limit. Ask for more explicitly:

$ gh org list --limit 100

The short form works too:

$ gh org list -L 100

Tip

--limit is a ceiling, not a request for that many rows. Seven organisations plus a limit of 100 still returns seven. Pick a sensible number for the account you are checking, and keep it visible in scripts so a later reader can see the intended boundary.

There is an alias, gh org ls, but the full command reads clearer in notes and automation. Confirm the syntax on this machine if a script has to run across several GitHub CLI installs:

$ gh org list --help
List organizations for the authenticated user.

FLAGS
  -L, --limit int   Maximum number of organizations to list (default 30)

The installed help spells it "organizations". This guide keeps British spelling in its own prose; command output and option text are reproduced exactly as the machine generated them.

4. Diagnose an empty or failed lookup

Start with the exit status and an authentication check. Skip sudo entirely: organisation membership belongs to the GitHub account, not the local root user, and elevated privileges buy you nothing here.

$ gh org list --limit 100
$ status=$?
$ printf 'gh org exit status: %s\n' "$status"
gh org exit status: 0
  • Zero status means the CLI finished, nothing more. It does not mean the account belongs to an organisation.
  • Non-zero status means run gh auth status next. Read its diagnostics, and check that the active host is the one you meant, especially on a machine set up for both github.com and a GitHub Enterprise Server.
  • Zero rows after successful auth means ask, do not assume network failure. Check the active account with gh auth status --active, then ask the account owner whether it should have organisation membership.

5. Keep scripts read-only and recoverable

gh org list takes no organisation-selection argument and performs no write, which makes it a safe discovery step ahead of something else. Save its output only where account data belongs, and protect any resulting log or report under your normal access controls. Keep organisation names, host names and authentication diagnostics out of a public issue or shared terminal recording unless that disclosure is actually intended.

There is nothing to undo for anything in this guide: no local configuration change, no GitHub organisation change. If a later step uses a discovered name to perform administration, stop and review that separate command first; this guide does not authorise or verify write operations.

Done means

  • Version and package checked. gh --version and the package metadata compared where the difference matters.
  • Account confirmed. gh auth status named the intended active account and host without exposing a token.
  • Organisations listed. gh org list returned the current account's visible organisations.
  • Limit raised when needed. A larger value used whenever the default 30 could be hiding rows.
  • Empty treated as data, not failure. Distinguished from an authentication or transport error.
  • Read-only throughout. No elevated privilege and no organisation-changing command used.