Getting Started

Installation

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

Requirements

✓Go 1.22+
✓PostgreSQL 14+ when DB_ENABLED=true — local, Docker, Kubernetes, AWS RDS, Supabase, etc.
✓Redis when REDIS_ENABLED=true — local, Docker, ElastiCache, Upstash, Redis Cloud, etc.
✓MinIO when MINIO_ENABLED=true — only if you wire bkgo/adapter/minio

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_ENABLED=true
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=mydb
DB_SSL_MODE=disable

REDIS_ENABLED=false
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

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

JWT_ENABLED=false
JWT_SECRET=

Adapters are optional. Set *_ENABLED flags, then wire them in main. JWT_SECRET is required only when JWT is enabled.

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