tbckr/sgpt: a Go rewrite of shell-gpt for terminal LLM queries

What tbckr/sgpt solves for terminal users

The problem is context switching. You are in a shell, you need a command you half remember, and the alternative is a browser tab, a login, and pasting the result back. SGPT collapses that into one command that returns an answer, a shell command, or a code snippet in the terminal you already have open. The README describes it as a CLI "designed for seamless interaction with OpenAI models directly from your terminal" and lists the target tasks: run queries, generate shell commands or code, and create images from text.

The audience is narrower than "developers". It is people who live in bash or zsh and want LLM output to land where they can pipe it, alias it, or run it. The README devotes a section to bash aliases and functions, which tells you the intended integration point is your shell profile, not an editor plugin or a chat UI. If your work happens inside an IDE, this is the wrong layer.

One thing to settle early: this is a Go implementation, not the Python project. The README says so directly and points to shell-gpt for the original, adding "Please keep this in mind when reporting issues." That sentence exists because people file bugs against the wrong repository. The two share a name and a purpose, not a codebase.

How sgpt talks to providers and templates prompts

The dependency list in go.mod is the clearest view of the architecture. github.com/sashabaranov/go-openai handles the OpenAI-compatible calls, github.com/spf13/cobra provides the command tree, and github.com/spf13/viper handles configuration. There is no separate HTTP client or provider abstraction library, so provider support beyond OpenAI is implemented in this repository on top of those pieces.

The README names the supported endpoints: OpenAI, OpenRouter, Requesty, Google Gemini, and local LLMs. It also documents GPT-4o, the GPT-4 Vision API, and o1 API support, plus chat capabilities and interactive shell sessions. Vision support means the tool can send image input, which is a different code path from text prompts and one the README covers in its own section.

Prompt templating is the most distinctive mechanism. According to the README, it uses Go text/template syntax and takes variables piped through stdin as YAML or JSON. That makes prompts data-driven: the template lives in a file, the variables come from a file or another command, and sgpt renders the result before sending it. For repeatable prompts across many inputs, that is a meaningfully different workflow from typing a question each time.

The binary itself is small in surface area. The Dockerfile builds with CGO_ENABLED=0 and runs on cgr.dev/chainguard/static, a static base image with no shell. A static binary with no libc dependency is what makes the single-file distribution model work across the Linux, macOS and Windows install paths.

Installing sgpt and running a first query

On macOS with Homebrew, the README gives one command. It installs from the project's own tap rather than homebrew-core.

brew install tbckr/tap/sgpt

On Windows with Scoop, you add the bucket first and then install from it, per the README.

scoop bucket add tbckr https://github.com/tbckr/scoop-bucket.git
scoop install tbckr/sgpt

If you have a Go toolchain, the README's Go path installs from the module path with the v2 major version segment.

go install github.com/tbckr/sgpt/v2/cmd/sgpt@latest

For containers, the README pulls the published image. Note that the image entrypoint is the sgpt binary itself, so arguments go straight to it.

docker pull ghcr.io/tbckr/sgpt:latest

On Linux, the README does not give a single install command. It says to download the latest release from the release page and use your distribution's package manager, and it lists Debian, Ubuntu, Arch Linux and Fedora as expected to work, with testing done on Ubuntu LTS releases.

Before any query, you need an API key. The README has a "Getting started: Obtaining an OpenAI API Key" section but the cleaned text does not show the exact environment variable name or the interactive setup command, so check the docs site rather than guessing a variable name. Once a key is configured, the basic query flow is a single sgpt invocation with your question as the argument, and the response prints to stdout where you can pipe it.

Generating shell commands is the risky part

The feature that justifies installing sgpt is also the one that should make you cautious. The README lists shell command generation and execution as a core capability, and separately documents interactive shell sessions. An LLM producing a command from a natural language description is useful exactly because the command is not something you already knew, which means you are least able to judge it at the moment you receive it.

The README does not, in the text available here, describe a confirmation prompt, a dry-run mode, a sandbox, or an allowlist for generated commands. Absence from the README is not proof those controls do not exist, but it does mean you cannot rely on the README to tell you what protects you. Before using command execution on anything with write access to a production system, read the docs site section on shell commands and confirm the exact confirmation behaviour in your installed version.

There is a second, quieter failure mode: the tool is only as good as the provider behind it. If you point sgpt at a local LLM through the local LLM support, output quality and latency are whatever that model gives you. sgpt does not add a validation layer. It formats a request and prints a response.

The wrong-tool case is automation. If you want generated commands applied unattended in CI, sgpt is the wrong tool for that job, because the design assumes a human at a terminal deciding whether to run what came back. Use it as an interactive assistant and keep it out of unattended pipelines that mutate infrastructure.

sgpt compared with the Python shell-gpt

The obvious alternative is shell-gpt, the Python project the README credits as the original implementation. The difference is not features on a checklist; it is the runtime you have to carry.

shell-gpt needs a Python environment. That may be trivial on your laptop and awkward on a minimal container, a locked-down build host, or a machine where you do not control the system Python. sgpt ships as a compiled binary. The Dockerfile builds with CGO_ENABLED=0 onto a static base image, and the Go install path produces a single executable. If your constraint is "no interpreter on the target host", the Go implementation removes that constraint entirely.

The trade-off runs the other way too. shell-gpt has a longer history and a separate community, and the README's warning about reporting issues implies the two projects have diverged enough that fixes do not flow automatically between them. Choosing sgpt means choosing this repository's release cadence and its docs, not the Python project's. If you already have shell-gpt working and your environment has Python, switching buys you a static binary and costs you familiarity. That is a real but modest gain, and it is worth being honest that it is not a rewrite of what the tool does.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-09-09, five days before this writing. That is a current repository by any reasonable reading. Release history supports the same conclusion: v2.21.1 on 2026-05-13, v2.21.2 on 2026-07-20, and v2.21.3 on 2026-09-03. Three releases across roughly four months, with patch-level version bumps, suggests incremental maintenance rather than a stalled project or a burst of new features.

Upgrade cost looks low on the surface. The Go module path carries the v2 major version, so the import path is stable within this major line, and the install paths (Homebrew tap, Scoop bucket, go install, container image) all resolve to the latest release. The repository also carries release-please-config.json and a .release-please-manifest.json, which is the tooling behind conventional-commit-driven release automation. Expect version bumps to track merged commits rather than a hand-curated roadmap.

The licence is MIT, stated in the README badge, the LICENSE file, and the SPDX identifier in the Dockerfile header. MIT is permissive: you can use, modify, and redistribute the code, including commercially, provided the copyright notice and permission notice are preserved. That is the general shape of the licence, not legal advice, and the Dockerfile's base images carry their own terms that are worth checking if you redistribute the container. Note also that the tool itself calls third-party model APIs, and those providers' terms apply to your usage independently of sgpt's licence.

Editorial conclusion

Adopt sgpt if you want a single static Go binary that can talk to OpenAI, OpenRouter, Requesty, Gemini or a local LLM, and you are comfortable with the execution risk of generated shell commands. Do not adopt it if you need documented rollback behaviour, a stable config reference in the README, or a tool whose upstream is the Python shell-gpt, since this repository is a separate Go implementation and issues belong here. Before wiring it into scripts, verify which provider and API key environment variables your target version reads, and check the docs site for the current config keys because the README does not list them.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. tbckr/sgpt on GitHub