generate Command¶

gtb generate scaffolds new projects and commands. It is part of the framework-developer CLI (the gtb binary), used while building a tool, not a runtime command shipped in your tool. See the Scaffolding and Generating Commands how-tos for task walkthroughs.

Usage¶

gtb generate <subcommand> [flags]

Subcommands¶

generate project¶

Generate a new project skeleton. Run without --name (or without --repo for a hosted project) in an interactive terminal to launch the wizard, whose pages are described in the scaffolding how-to; otherwise supply the flags directly. The wizard and the flags produce the same manifest.

Core:

Help channel (used when --help-type is slack/teams): --slack-channel, --slack-team, --teams-channel, --teams-team. The channel is required for its type; a type outside slack, teams, none is refused.

Features accepted by --features:

--features replaces the default set rather than extending it, so a selection must name every feature the tool should ship with: --features gitlab alone yields a tool with the six default built-ins off. An unrecognised name is rejected before anything is written.

Every feature can be toggled after generation with gtb enable/gtb disable, which leaves the tree in line in one command: the root command, the adapter files and any derived field a newly enabled feature needs (the ai feature's provider list) are written by the same run, and no regenerate is needed afterwards.

Adapters. A chat provider or a forge is a module the tool blank-imports from its own main package, and the generator writes those imports from the manifest into two DO NOT EDIT files beside keychain.go. Each exists only while the tool uses it: chat.go while a provider is linked or ai is on, forge.go while a forge feature is enabled. A tool with neither has neither file.

Two things are easy to run together and are deliberately separate. chat.providers is the wiring: which provider modules the binary links, a shortcut for a tool that uses go/chat from its own code as much as for one that uses GTB's AI features, and the place new providers appear as they become available. The ai feature is the switch for GTB's AI-based features: the ai config section and ai.provider, the init ai wizard, docs ask, the chat defaults bundle and the doctor check. A tool can link providers without ai (keryx does), and ai needs at least one linked provider to do anything.

Nothing is linked unless asked: --chat-providers names the list, and the ai feature with no list takes every known provider, since a tool that offers GTB's AI features is configured by its consumers the way gtb itself is. Generation only emits the import; what the running tool's init wizard and doctor can set up for a provider is a separate, narrower question (today: the three API-key providers and the local CLIs, which need nothing; Vertex, Bedrock and Azure are configured through go/chat's own settings). A name no module registers is refused, at generation and at regenerate.

A durable override is a manifest field, never a deleted file. Every DO NOT EDIT file under cmd/<name>/ (chat.go, forge.go, keychain.go, the chat/assets bundle) and pkg/cmd/root/signing.go is re-emitted from the manifest by every command that writes the manifest, so its presence is a fact about the manifest and its absence is temporary. To ship no chat provider with ai on, set chat.providers: []; to drop the linked modules, gtb unset chat.providers (gtb disable ai turns the AI features off and leaves the wiring, saying so); to drop the keychain, gtb disable keychain; to turn signing off, gtb disable signing. A project generated before the chat: block existed has no block at all, and gets the full list written into its manifest the first time it is regenerated (or enable ai is run) with ai enabled.

The generated go.mod names no gtb tool line. The manifest's version.gtb is the pin, regenerate refuses an older gtb, and the README carries go install gitlab.com/phpboyscout/go-tool-base/cli/cmd/gtb@<version>. Nor does it name golangci-lint or mockery: the justfile and CI run the installed binaries, and the golangci-lint tool line pinned v1 and dragged an old viper whose cloud.google.com/go/compute made go mod tidy ambiguous the moment chat-gemini was linked. Only the framework's own cmd/changelog and cmd/docs remain.

Every author setting has one home. Each flag above that says "recorded as" names the manifest field it writes, and regenerate reads that field back unchanged; cli/pkg/generator/author_settings.go is the table, and a test holds it and SkeletonConfig to each other (spec 0197 D1, D2). Nothing about a generated project depends on the machine regenerate runs on.

Chat defaults. AI in a generated tool is one decision with several parts: which providers to link, which is the default, which model, and the endpoint a few providers need. The manifest records the answer under chat: and the generator ships it as the tool's lowest config layer, beside the file that links the modules:

chat:
  providers: [claude, claude-local]
  default:
    provider: claude
    model: claude-opus-5     # optional
    base_url: ""             # openai-compatible, azure-openai
    api_version: ""          # azure-openai
    project: ""              # gemini-vertex
    location: ""             # gemini-vertex, bedrock

Both are DO NOT EDIT files rewritten from the manifest by regenerate project, and both are absent when the manifest names no default. One linked provider is its own default. With several, name one: an older manifest that links several and names none regenerates without an author default and warns naming chat.default.provider; the tool then falls back to its runtime resolution. Credentials never appear in the manifest or these files; they are the end user's, captured by init ai or supplied through the environment.

Git lifecycle (the new project is git-initialised with an initial commit by default):

Release signing (off by default; supplying --signing-email implies --signing):

Environment¶

generate command¶

Generate a new command or subcommand (optionally AI-converted from a script).

All generate subcommands also accept these persistent flags (for AI-assisted generation): --provider (any chat provider the gtb binary links; gtb generate --help lists them, and the list is chat.ProviderModules()), --model (AI model), and --dry-run (preview changes without writing files).

generate add-flag¶

Add a new flag to an existing command (see Add Flags).

generate docs¶

Generate Markdown docs for a command or package.

One of --command/--package/--source is required. (--source is deprecated; use --command.)

Docs are emitted in the project's layout (docs_layout in .gtb/manifest.yaml): the Diátaxis quadrant tree (docs/reference/cli/, docs/explanation/components/) for new projects, or the legacy flat tree (docs/commands/, docs/packages/). See Generating Documentation → "Documentation layout".

generate man¶

Generate roff man pages for the command tree.

generate protect / generate unprotect¶

gtb generate protect <command-path> marks a command so regeneration won't overwrite it; unprotect reverses it. See Configure Generator Ignore.

Run any subcommand with --help for the complete, authoritative flag set.