insighta — CLI for Insighta Labs+

A Go CLI that authenticates via GitHub OAuth (PKCE) and talks to the Insighta Labs+ backend. Globally installable; credentials live at ~/.insighta/credentials.json.

Install

# from source
git clone <this-repo> && cd insighta-cli
go install .

# verify
insighta version

After go install, the insighta binary lives in $GOPATH/bin (or $HOME/go/bin) which should already be on your PATH. If not:

export PATH="$PATH:$(go env GOPATH)/bin"

Configure

# Optional — defaults to the live deployment
export INSIGHTA_API_URL=https://be-hng-1.onrender.com

# Optional — overrides the GitHub client_id the CLI fetches from the backend
export INSIGHTA_CLIENT_ID=Iv1.xxxxx

The CLI's local OAuth callback listens on http://127.0.0.1:9876/callback during insighta login. The GitHub OAuth App's "Authorization callback URL" must include this loopback callback (see the backend repo's deployment notes).

Usage

Auth

insighta login        # opens GitHub OAuth in your browser
insighta whoami       # GET /api/users/me
insighta logout       # revokes refresh + clears local creds

Profiles

insighta profiles list
insighta profiles list --gender male --country NG --age-group adult
insighta profiles list --min-age 25 --max-age 40
insighta profiles list --sort-by age --order desc
insighta profiles list --page 2 --limit 20

insighta profiles get <id>
insighta profiles search "young males from nigeria"
insighta profiles create --name "Harriet Tubman"     # admin only
insighta profiles export --format csv --gender male --country NG
insighta profiles export --format csv --out ./out.csv

profiles create requires the admin role. Analysts can read and search and export, but any non-GET request returns 403.

How auth works

insighta login
   │
   ├── generates state + code_verifier + code_challenge (PKCE)
   ├── starts a one-shot HTTP server on 127.0.0.1:9876
   ├── opens browser to GitHub /authorize?...&code_challenge=...
   │
github.com  →  redirects browser to 127.0.0.1:9876/callback?code=…&state=…
   │
   ├── CLI validates state matches
   ├── POSTs { code, code_verifier, redirect_uri } to backend
   │     /auth/github/exchange
   │
backend  →  exchanges with GitHub, upserts user, returns
            { access_token, refresh_token, user }
   │
   └── CLI saves credentials to ~/.insighta/credentials.json

Token handling

• Access tokens (3-minute expiry) are sent on every request as Authorization: Bearer <token> plus X-API-Version: 1.
• On 401 invalid_token the CLI automatically calls POST /auth/refresh once, retries the original request, and persists the rotated pair.
• If refresh also fails (refresh expired or revoked), the CLI returns the error to the user with "not logged in (run: insighta login)".

Project layout

main.go      command dispatcher
auth.go      login (PKCE), logout, whoami; local callback server
api.go       HTTP client with auto-refresh on 401
creds.go     ~/.insighta/credentials.json read/write
profiles.go  list, get, search, create, export commands
render.go    table rendering, spinner, helpers

CI

.github/workflows/ci.yml runs gofmt, go vet, go build, go test on every PR + push to main.

HNG-WEPAPP-3

HNG_3_CLI