lazygocd
~/lazygocd/quickstart

Quickstart

There is no setup wizard outside the app. Run lazygocd and the connect form opens right in the terminal, walks you through four inputs, and drops you into the dashboard.

First run: the connect form

  1. Server URL

    Your GoCD base URL including the /go path, for example https://gocd.example.com/go, with no trailing slash.

  2. Auth method

    An arrow-key choice between username & password and an access token. Tokens are recommended; create one in GoCD under your user's Access Tokens page.

  3. Credential

    The token or password, typed masked. If your server has no auth at all, leave the username blank.

  4. Done

    On confirm it saves the config and loads straight into the dashboard. Certificates are always verified; there is no prompt to turn that off. Press A any time later to reopen the same form as "Reconnect to GoCD", for example after a token expires.

Where config lives

Everything is written under ~/.config/lazygocd/. The directory is created mode 0700 and every file in it is written mode 0600: the config holds a plaintext credential, and the cache lists every pipeline name on your server.

~/.config/lazygocd/config.toml 
server_url = "https://gocd.example.com/go"

# one of the two auth styles:
auth_token = "your-access-token"          # recommended
# username = "ci-viewer"
# password = "..."

insecure_skip_verify = false              # true only for self-signed certs
poll_interval_secs = 30                    # dashboard/history auto-refresh

# optional: only needed to check private repos' latest commit
# github_token = "ghp_..."  (optional: gh auth token is used automatically if unset)
# github_api_base = "https://ghe.example.com/api/v3"  (GitHub Enterprise)
# notifications = true  (desktop alerts when a favorite starts failing)
# editor = "code --wait"  (what 'e' opens logs in; also nvim, zed --wait)
FileWhat it holds
config.tomlServer URL, credentials, TLS setting, poll interval, optional GitHub token. Mode 0600.
dashboard_cache.jsonThe last successful dashboard load, so the next launch paints instantly. Mode 0600; it lists every pipeline and group name. Safe to delete.
favorites.jsonNames of starred pipelines, pinned to the top of the tree. Mode 0600.

Shell completion and one-shot lookups

Completion fills in your actual pipeline names from the local dashboard cache. No network, so tab stays instant.

Homebrew does this for you. The formula installs zsh, bash and fish completions plus the man page, so there is nothing to run. Open a new shell and lazygocd dev plus tab already offers your pipelines.

For a cargo install or a downloaded binary, generate them into a directory your shell already searches:

lazygocd completions zsh > "$(brew --prefix)/share/zsh/site-functions/_lazygocd"
lazygocd man > "$(brew --prefix)/share/man/man1/lazygocd.1"

A path like ~/.zfunc works only if you added it to fpath before compinit runs; echo $fpath shows what your shell searches today. The cache appears after your first successful launch, so completion is empty until you have run lazygocd once.

You do not have to open the interface at all. Naming a pipeline prints its latest run and exits, --logs -f tails a running job, and --history lists recent runs. See the CLI section on Features.

lazygocd web-app
lazygocd web-app --logs -f
lazygocd web-app --json | jq -r '.status'

Environment variable overrides

Env vars always win over the config file. Handy for scripting, CI, or trying a second server without touching your saved config. Setting a full set (URL plus a credential) skips the connect form entirely.

VariableOverrides
GOCD_URLServer base URL, e.g. https://gocd.example.com/go
GOCD_USERNAMEUsername for basic auth
GOCD_PASSWORDPassword for basic auth
GOCD_TOKENAccess token; used instead of username/password when set
GOCD_INSECUREAny value skips TLS certificate verification (e.g. GOCD_INSECURE=1). Your token or password then rides a connection nothing authenticates, so anything on the path can read it.
GITHUB_TOKENGitHub personal access token for private-repo commit checks
 
# one-shot session against a different server, config file untouched
$ GOCD_URL=https://gocd.example.com/go GOCD_TOKEN=your-token lazygocd
tip Press @ inside the app to connect a GitHub token interactively instead of exporting GITHUB_TOKEN. It's optional either way; public repos are checked unauthenticated (rate-limited).
Learn the keys How it stays fast