Skip to content

How to lint schemas

conga-lint finds the schema mistakes the program otherwise reports one at a time at startup, and leaf commands without a Run method, which fail only when a user invokes them. This guide lints an example cloudctl program with three mistakes, then allows tag keys that other code reads.

Declare conga-lint as a tool dependency:

Terminal window
go get -tool github.com/conga-sh/conga/cmd/conga-lint@latest

Run it with go tool over your packages. This example declares --verbose on both the root and deploy, misspells help as hlep, and gives StatusCmd no Run method:

main.go
package main
import (
"context"
"fmt"
"github.com/conga-sh/conga"
)
type CLI struct {
Verbose conga.OptionalFlag[bool] `help:"Print each step" short:"v"`
Deploy conga.Command[DeployCmd] `summary:"Deploy a manifest"`
Status conga.Command[StatusCmd] `summary:"Show service status"`
}
type DeployCmd struct {
Error: Verbose conga.OptionalFlag[bool] `help:"Print deploy details"`
Error: Replicas conga.OptionalFlag[int] `default:"3" hlep:"Number of replicas"`
}
func (d *DeployCmd) Run(ctx context.Context, session *conga.Session) error {
fmt.Fprintf(session.Stdout(), "deploying %d replicas\n", d.Replicas.Get())
return nil
}
Error:type StatusCmd struct{}
func main() {
app := conga.New[CLI]().
EnableCompletion().
Name("cloudctl")
if err := app.Run(); err != nil {
app.Exit(err)
}
}
Terminal window
$ go tool conga-lint ./...
Error:main.go:18:2: struct DeployCmd field Verbose: schema error: duplicate flag: --verbose (already declared by struct CLI field Verbose on an ancestor command)
Error:main.go:19:2: struct DeployCmd field Replicas: schema error: invalid struct tag: unknown struct tag "hlep" (did you mean "help"?). Use app.AllowTags("hlep") to permit external tags
Error:main.go:28:6: struct StatusCmd: schema error: runner not implemented: implement conga.Runner: Run(context.Context, *conga.Session) error

Running the program shows only the first mistake:

Terminal window
$ cloudctl status
Error:cloudctl: error: struct DeployCmd field Replicas: schema error: invalid struct tag: unknown struct tag "hlep" (did you mean "help"?). Use app.AllowTags("hlep") to permit external tags

Go’s ./... pattern skips directories that start with _, such as _examples/, so name those paths explicitly.

-builder-order also checks the builder calls at each conga.New against a canonical order. Identity calls such as Name come first, then the Enable* and Disable* toggles, then behavior, then execution. In this example EnableCompletion comes before Name:

Terminal window
$ go tool conga-lint -builder-order ./...
Error:main.go:33:3: builder call order violation: Name (rank 1) called after EnableCompletion (rank 9); use -fix to reorder
main.go:18:2: struct DeployCmd field Verbose: schema error: duplicate flag: --verbose (already declared by struct CLI field Verbose on an ancestor command)
main.go:19:2: struct DeployCmd field Replicas: schema error: invalid struct tag: unknown struct tag "hlep" (did you mean "help"?). Use app.AllowTags("hlep") to permit external tags
main.go:28:6: struct StatusCmd: schema error: runner not implemented: implement conga.Runner: Run(context.Context, *conga.Session) error

To reorder the calls in place, add -fix. It rewrites the files and prints nothing:

Terminal window
go tool conga-lint -builder-order -fix ./...

Add -diff to print the change without applying it. -fix moves calls only where the swap is safe, and never moves Use(...), which runs plugin code.

With the three mistakes fixed as well, the check passes and prints nothing (exit 0):

Terminal window
go tool conga-lint -builder-order ./...

-builder-order-spec replaces the canonical order with your own. Give it method names separated by commas, or @path to read them one per line from a file. Methods the list leaves out can go anywhere. On the fixed example, a spec that puts EnableCompletion before Name turns the canonical order into a violation:

Terminal window
$ go tool conga-lint -builder-order -builder-order-spec EnableCompletion,Name ./...
Error:main.go:38:3: builder call order violation: EnableCompletion (rank 1) called after Name (rank 2); use -fix to reorder

The spec takes effect only together with -builder-order. A name that isn’t an App method stops the run with exit 2 and lists the valid names.

CONGA rejects tag keys it doesn’t recognize on flag, argument, and subcommand fields, so a misspelled tag fails at startup instead of being ignored. It accepts the keys that common libraries read, such as json, yaml, validate, and db. Any other key looks the same to CONGA as a misspelling, so it fails too. The AllowTags builder method lists the extra keys CONGA accepts. Allowed foreign tags lists the default keys.

In this variation of the fixed example, DeployCmd is also stored with the MongoDB driver, which reads bson, and written to a deploy history by the program’s own encoder, which reads history:

main.go
type DeployCmd struct {
Replicas conga.OptionalFlag[int] `bson:"replicas" default:"3" help:"Number of replicas" history:"replicas"`
Token conga.OptionalFlag[string] `help:"API token" history:"-"`
}

The analyzer reports the first unknown key on each field:

Terminal window
$ go tool conga-lint ./...
Error:main.go:18:2: struct DeployCmd field Replicas: schema error: invalid struct tag: unknown struct tag "bson". Use app.AllowTags("bson") to permit external tags
Error:main.go:19:2: struct DeployCmd field Token: schema error: invalid struct tag: unknown struct tag "history". Use app.AllowTags("history") to permit external tags

The program fails at startup with the first of them, exit 1:

Terminal window
$ cloudctl deploy
Error:cloudctl: error: struct DeployCmd field Replicas: schema error: invalid struct tag: unknown struct tag "bson". Use app.AllowTags("bson") to permit external tags

List both keys in AllowTags:

main.go
func main() {
app := conga.New[CLI]().
Name("cloudctl").
EnableCompletion().
AllowTags("bson", "history")
if err := app.Run(); err != nil {
app.Exit(err)
}
}

The analyzer now prints nothing (exit 0), and the program runs:

Terminal window
$ cloudctl deploy
deploying 3 replicas

The analyzer reads the keys from string literals in the AllowTags call. When the call takes a variable, such as AllowTags(tags...), it can’t tell which keys are allowed, so it reports no unknown tags for that app.

AllowTags matches keys exactly, so a misspelled histroy still fails. The hint names the allowed key it was probably meant to be:

Terminal window
$ go tool conga-lint ./...
Error:main.go:18:2: struct DeployCmd field Replicas: schema error: invalid struct tag: unknown struct tag "histroy" (did you mean "history"?)

CONGA checks plain fields, which aren’t containers, only for its own tags, so a Note string field tagged history:"note" needs no AllowTags.

Mistake Without the linter With conga-lint
A misspelled or unknown tag Startup error on every run, exit 1 Reported with the field and a “did you mean” hint
A tag key that other code reads, outside the built-in list Startup error on every run, exit 1 Reported unless the key is listed in AllowTags
A key listed in AllowTags Accepted Accepted when the call uses string literals
A misspelling of a key listed in AllowTags Startup error on every run, exit 1 Reported, with a hint that names the allowed key
A descendant redeclares a parent’s flag Startup error on every run, exit 1 Reported at the descendant’s field
A leaf command has no Run method Error only when a user invokes that command, exit 1 Reported at the struct
Builder calls out of order No effect Reported with -builder-order, and -fix reorders them
-builder-order-spec names an unknown method No effect invalid builder order spec: unknown App method "Nmae" and the valid names, exit 2
-builder-order-spec without -builder-order No effect The spec is ignored and no order check runs, exit 0