Half the friction of writing a gh extension is the boilerplate before your first line of logic, and gh extension create exists to skip it. This installed GitHub CLI is 2.87.3, and its wizard offers an interactive script template plus Go and other precompiled templates.
Allow roughly 10 minutes for the scaffold and a first look round it. You need a shell, GitHub CLI 2.87.3 or compatible, a writable parent directory, and no root privileges. Have a short extension name ready: lowercase letters and hyphens, such as whoami. The command only creates a project locally; it does not publish a GitHub repository for you.
gh-, and the repository must provide an executable matching the extension name.Checkpoint: decide whether you want an interpreted script or a compiled program before you run anything. Use the script template for a portable shell program, Go when you want Go scaffolding and a compiled extension, and other when you will bring a different compiled language and build process.
Confirm the version and the available flag before creating anything:
gh version
gh extension create --help
mkdir -p "$HOME/src/gh-extensions"
cd "$HOME/src/gh-extensions"
On the machine used for this guide, the first command reports gh version 2.87.3 (2026-02-23). The help output shows one option, --precompiled, accepting go or other. This is a plain filesystem operation, so no sudo.
Keep the parent directory separate from any existing repository while you are learning. That way it is obvious which files the scaffold created, and you will not mix starter files into an unrelated project by accident.
Run this from the clean parent directory, changing the name if you like:
gh extension create whoami
Supplying a name skips the no-argument wizard and creates the project straight away. GitHub's own documentation describes this template as a Bash starter script. Follow whatever the command prints, then look round the result:
cd gh-whoami
find . -maxdepth 3 -type f -print | sort
git status --short
The exact file list is template output and can change between GitHub CLI releases, which is why find beats assuming a fixed layout. Before you try it, check the generated script is readable, understand every command inside it, and confirm the entry point is executable.
Checkpoint: a shell script is the right call, stop here. Open the entry point, replace the example behaviour, and remember that arguments typed after gh whoami are passed straight through to your script.
If you skipped the script project, return to the clean parent directory. The Go template needs an explicit flag:
cd "$HOME/src/gh-extensions"
gh extension create --precompiled=go whoami-go
cd gh-whoami-go
find . -maxdepth 3 -type f -print | sort
git status --short
The documented Go template ships Go scaffolding, a workflow, and starter code. Inspect the generated workflow before you trust it, and do not assume the project builds just because the files exist: compile and test it using what the command and the project files actually tell you.
For a precompiled extension the executable is a build output. Keep generated binaries out of version control unless the project genuinely needs otherwise, and a typical local build must leave an executable at the project root with the name the extension expects. Verify that against the generated files and current documentation before you install locally.
Choose other when you are writing in a different compiled language:
cd "$HOME/src/gh-extensions"
gh extension create --precompiled=other whoami-native
cd gh-whoami-native
find . -maxdepth 3 -type f -print | sort
git status --short
This template gives you the workflow scaffolding but leaves the implementation to you. GitHub's documentation says to put your build commands in script/build.sh so the extension can be built automatically. Read that file before you edit it, make the build produce the required executable, and test it locally.
Safety boundary: a build script executes commands from the project. Do not run it until you have read it and confirmed its toolchain, download sources and output paths. The normal workflow needs no elevated privileges.
For a script extension, make the entry point executable and install the current directory as a local extension only once you have reviewed it:
chmod +x ./whoami
gh extension install .
gh extension list
gh whoami --help
The install step changes your GitHub CLI extension state, so skip it if you only wanted a scaffold. On supported systems it manages a local installation linked to the project. To undo it:
gh extension remove whoami
For a compiled project, build first and check the expected root executable exists and runs. Follow the generated project's own instructions, then install from the project directory and invoke the extension. If something fails, read the output before you start changing permissions or adding dependencies: a missing executable, a non-executable file, a wrong name, or an unavailable interpreter are the usual culprits.
Publishing is a separate, deliberate step. Before it:
.gitignore so build output does not leak into the repository.gh- prefix, since users will invoke it as gh followed by the extension name..exe suffix for Windows assets.gh version and which template you need.gh expects.gh extension remove.