CLI Overview

keel is the official CLI for the Keel ecosystem to create, initialize, and maintain structured Go projects.

This section is based on the real code of keel and ss-keel-core, including tests and generator templates.

Sources of truth

keel/cmd/*: real definition of commands, arguments, aliases and flags.
keel/internal/generator/templates/*: exact files and structure generated by the CLI.
keel/cmd/*_test.go: expected behavior cases and errors.
ss-keel-core/core/*: resulting HTTP runtime (/health, /docs, OpenAPI, lifecycle).

What the CLI solves

Creating projects ready to work with (keel new)
Adopting Keel in existing projects (keel init)
Generating components with automatic wiring (keel generate)
Installing, removing, and upgrading addons (keel add, keel addon)
Running project scripts (keel run)
Diagnosing project health (keel doctor)
Managing environment variables (keel env)
Shell autocompletion (keel completion)

Available commands

Command	Alias	Purpose
`keel new [project-name]`	`keel n`	Creates a new project from official templates
`keel init`	—	Generates `keel.toml` in an existing project
`keel generate [type] [name]`	`keel g`	Generates modules/components and updates `cmd/main.go`
`keel add [alias\|repo]`	—	Installs an addon from the official registry or a direct GitHub repo
`keel addon remove <alias>`	—	Removes an installed addon and undoes its wiring
`keel addon upgrade [alias]`	—	Upgrades one or all installed addons
`keel run [script]`	—	Runs scripts from `[scripts]` in `keel.toml`
`keel doctor`	—	Diagnoses project health (keel.toml, addons, env vars, build)
`keel env sync`	—	Generates/updates `.env.example` from `application.properties`
`keel env generate`	—	Generates `.env` with only missing keys
`keel env check`	—	Validates required env vars (useful in CI)
`keel telemetry status\|enable\|disable`	—	Manages anonymous usage data collection
`keel upgrade`	—	Updates Keel CLI via the detected installation source
`keel completion ...`	—	Generates/installs autocompletion (`zsh`, `bash`, `fish`, `powershell`)
`keel version`	`keel --version`, `-v`	Shows version, commit, build date, and platform

Recommended workflow

# 1) Install CLI
go install github.com/slice-soft/keel@latest

# 2) Create project
keel new my-api
cd my-api

# 3) Run dev environment
keel run dev

# 4) Generate first module
keel generate module users --gorm

# 5) Install another addon
keel add jwt

# 6) Check commands and version
keel --help
keel --version

Relationship with `ss-keel-core`

The CLI generates code that directly uses ss-keel-core:

core.New(core.KConfig{...})
app.Use(...)
app.RegisterController(...)
app.Listen()

When you run a generated project, you inherit the core’s behavior:

GET /health (if DisableHealth is false)
GET /docs and GET /docs/openapi.json when Env != "production"
standardized HTTP error handling and graceful shutdown