Getting Started

Installation

bkgo requires Go 1.22 or later. Install the package and the CLI separately.

Requirements

✓Go 1.22+
✓PostgreSQL 14+ — any source: local, Docker, Kubernetes, AWS RDS, Supabase, etc.
✓Redis (optional) — any source: local, Docker, ElastiCache, Upstash, Redis Cloud, etc.
✓MinIO (optional) — only needed if you use bkgo/adapter/minio for file storage

No specific infrastructure required. bkgo reads all connection details from environment variables. Whether you run services via Docker Compose, Kubernetes, a managed cloud provider, or a local install — just set the corresponding env vars and bkgo connects the same way.

Install the package

Add bkgo to your Go module:

go get github.com/BounkhongDev/bkgo

Import only the packages you need — each one is independent:

import (
    gormadapter "github.com/BounkhongDev/bkgo/adapter/gorm"
    "github.com/BounkhongDev/bkgo/adapter/redis"
    "github.com/BounkhongDev/bkgo/adapter/jwt"
    "github.com/BounkhongDev/bkgo/config"
    "github.com/BounkhongDev/bkgo/contract"
    "github.com/BounkhongDev/bkgo/errs"
    "github.com/BounkhongDev/bkgo/middleware"
    "github.com/BounkhongDev/bkgo/response"
)

Install the CLI

Install the bkgo CLI globally:

go install github.com/BounkhongDev/bkgo/cmd/bkgo@latest

Verify the install:

bkgo --version

Staying up to date

The CLI can upgrade both itself and the bkgo dependency in your project.

bkgo upgrade         # bump bkgo in this project's go.mod
bkgo upgrade --cli   # reinstall the CLI binary itself

bkgo uninstall removes the package from go.mod, and bkgo uninstall --cli deletes the binary again.

See the full CLI reference →

Environment setup

bkgo reads configuration from a .env file. Create one at your project root:

APP_NAME=myapp
APP_PORT=8080
APP_ENV=development

DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=mydb
DB_SSLMODE=disable

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=uploads
MINIO_USE_SSL=false

JWT_SECRET=change-me-in-production

JWT_SECRET must be set — config.Load() returns an error if it is empty.

Agent Skills

bkgo ships a SKILL.md for AI coding agents (Claude Code, Cursor, Codex, etc.). It enforces the bkgo CLI workflow — inspecting project structure, generating modules with bkgo g module, and following the Hexagonal Architecture layer rules.

Add it to your own project:

npx skills add BounkhongDev/bkgo