Skip to main content

gws generate-template

Emit a known-good template (Dockerfile, Kubernetes Deployment, Service, GRPCRoute, .dockerignore, or .air.toml) for a given framework, with {{SERVICE_NAME}} and {{PORT}} substituted.

The templates are the same ones gws up uses internally, so a Dockerfile or Deployment emitted by gws generate-template is byte-identical to what would be generated automatically — only the {{SERVICE_NAME}} and {{PORT}} placeholders are filled in (other framework-specific placeholders like {{GO_VERSION}} or {{ENTRYPOINT}} are left in place and a stderr warning lists them so you know what to fill in).

Mostly invoked by the /gws-setup skill so the AI customizes a known-good template instead of imagining one from scratch.

Usage​

gws generate-template [framework] [kind] [options]
gws generate-template --list
ArgumentDescription
frameworkFramework key — run with --list to see all (e.g. go-gin, python-fastapi, nodejs-express, nestjs, nodejs-adonisjs, hugo, python-celery, …).
kindOne of dockerfile, deployment, service, grpcroute, dockerignore, air-toml.
FlagDescription
--port <port>Substitute {{PORT}}. Defaults to the framework's default port.
--name <name>Substitute {{SERVICE_NAME}}. Defaults to the framework key.
--listList all available (framework, kind) pairs as JSON.

Auth: not required.

Contract guarantees​

  • No USER directive — running as root in dev avoids a class of file-sync and bind-mount issues.
  • Single-stage Dockerfile — multi-stage breaks bidirectional file sync (the source must live in the final image).
  • Full base image — never distroless or scratch (same reason).
  • EXPOSE matches --port — the Dockerfile, the K8s containerPort, and gws.json's port always agree.
  • No metadata.namespace in K8s manifests — namespace is set by gws up at apply time as sanitizeNamespace(${project}-${worktree}).

These constraints are pinned by tests in gws/test/commands/generate-template.test.ts and aren't optional — they're how gws up actually works.

Errors​

CodeCause
EFRAMEWORK_NOT_TEMPLATEDUnknown framework or kind. The error message includes the supported list. Same code is also emitted by gws generate-helm-values so /gws-setup can branch programmatically.

Examples​

# Catalog
gws generate-template --list | jq '.frameworks[] | select(.language == "go")'

# Single-stage Dockerfile for a Gin service on port 9000
gws generate-template go-gin dockerfile --name api --port 9000 > .gws/services/api/Dockerfile

# Namespace-free K8s Deployment
gws generate-template python-fastapi deployment --name api --port 8000

# Service manifest with matching targetPort
gws generate-template python-fastapi service --name api --port 8000

# Hot-reload config for Air (Go)
gws generate-template go-gin air-toml > .gws/services/api/.air.toml

See also​