What Is the gogcli Schema Command? A Complete Technical Guide

The gogcli schema command generates a machine-readable JSON description of the entire command-line interface, including all commands, flags, arguments, and sub-commands.

The gogcli schema command is a built-in introspection tool in the steipete/gogcli repository that exports the complete structure of the CLI as structured data. This functionality enables automated tooling, IDE integrations, and documentation generators to programmatically understand available commands and their configurations without parsing help text manually.

What Does the gogcli Schema Command Output?

The command emits a JSON document conforming to schema version 1, which serves as a stable contract for consumers. This output captures every aspect of the CLI definition, from top-level commands to individual flag attributes.

Schema Structure and Metadata

The root object contains three primary fields: schema_version (currently hardcoded to 1), build (the exact binary version from VersionString()), and command (the root node descriptor). Each node recursively describes:

• Command metadata: name, aliases, help text, usage string, and hidden status
• Flags: complete flag specifications including name, short form, type, defaults, environment variable bindings, and negation support
• Positional arguments: name, help text, and type information
• Sub-commands: nested command structures sorted alphabetically
• Requirements: lists of required flags in --flag-name format

Flag and Argument Introspection

The schema exposes detailed flag definitions through the flags array. Each entry includes the Go type (via reflect.Type.String()), allowed values for enums, placeholder text for usage generation, and whether the flag supports negation (e.g., --no-flag). Environment variable bindings are explicitly listed, enabling tooling to understand configuration precedence.

How to Use the gogcli Schema Command

The gogcli schema command supports optional arguments to filter output and reveal internal implementation details.

Basic Usage

Generate the complete schema for the entire CLI:

gogcli schema | jq .

This pipes the JSON through jq for formatted viewing, displaying the full command tree starting from the root.

Filtering by Command Path

To generate a schema for a specific sub-command, provide the command path as arguments:

gogcli schema drive ls | jq .

This limits the output to only the drive ls command and its flags, arguments, and sub-commands (if any). The implementation walks the Kong command tree using findCommandNode to locate the specific node before serialization.

Including Hidden Commands and Flags

By default, the schema omits hidden commands and flags intended for internal use. To include these in the output:

gogcli schema --include-hidden | jq .

This sets the IncludeHidden field in the SchemaCmd struct to true, passing this flag through to node.AllFlags(hide) and the recursive buildSchemaNode function to bypass filtering of hidden elements.

Exporting to File

Save the schema to a file for later processing or version control:

gogcli schema > gogcli-schema.json

This is particularly useful for CI/CD pipelines that validate tooling against specific CLI versions or for generating static documentation.

Implementation Details in the gogcli Source Code

The gogcli schema command is implemented in internal/cmd/schema.go, with registration occurring in internal/cmd/root.go.

The SchemaCmd Struct

The command definition uses Kong's declarative struct tags to define arguments:

type SchemaCmd struct {
    Command       []string `arg:"" optional:"" name:"command" help:"Optional command path to describe (e.g. drive ls). Default: entire CLI"`
    IncludeHidden bool     `name:"include-hidden" help:"Include hidden commands and flags"`
}

The Command field captures the optional path as a string slice, while IncludeHidden controls visibility filtering throughout the tree traversal.

Tree Traversal and Node Building

The Run method retrieves the Kong model via kctx.Model.Node, then optionally navigates to a specific command using findCommandNode. The core conversion logic resides in buildSchemaNode, which recursively transforms Kong nodes into serializable schemaNode structures.

This function respects the hide parameter (derived from IncludeHidden) when calling node.AllFlags(hide) and filtering sub-commands. It extracts detailed metadata including:

• Type information via reflect.Type.String()
• Environment variable bindings
• Flag negation support
• Required flag lists

JSON Output Generation

The final output wraps the command tree in a schemaDoc struct:

doc := schemaDoc{
    SchemaVersion: 1,
    Build:         VersionString(),
    Command:       buildSchemaNode(node, hide),
}
return outfmt.WriteJSON(ctx, os.Stdout, doc)

The outfmt.WriteJSON helper (from internal/outfmt/json.go) handles the actual serialization to stdout, ensuring consistent formatting across the application.

Practical Use Cases for the Schema Command

The gogcli schema command serves several technical workflows beyond simple documentation.

Automated Tooling and IDE Integration

Development environments and automation tools can parse the JSON output to provide context-aware completions, validation, and inline documentation. By consuming the schema programmatically, tools avoid the fragility of parsing human-readable help text and instead rely on the stable schema version 1 contract.

Debugging and Verification

Developers use --include-hidden to audit internal commands and flags that are normally suppressed from end-user documentation. This is essential for verifying that flag definitions, environment variable bindings, and requirement constraints match architectural specifications during development.

Version Tracking and Reproducibility

The build field in the schema output captures the exact binary version via VersionString(). CI/CD pipelines can archive schema files alongside build artifacts to ensure that downstream tooling validates against the precise CLI version used in production, preventing drift between documented capabilities and actual implementation.

Summary

• The gogcli schema command exports the complete CLI structure as a JSON document following schema version 1.
• Output includes commands, flags, arguments, environment variables, and hidden elements when using --include-hidden.
• Filter specific command branches by providing a command path (e.g., drive ls).
• Implementation resides in internal/cmd/schema.go, using Kong's model traversal via buildSchemaNode.
• Primary use cases include automation tooling, IDE integration, debugging, and version tracking.

Frequently Asked Questions

What format does the gogcli schema command use?

The command outputs JSON conforming to schema version 1. This structured format includes metadata such as the binary build version, command hierarchies, flag definitions with Go types, environment variable bindings, and positional argument specifications. The JSON structure is stable and designed for programmatic consumption by automation tools and integrations.

Can I export the schema to a file instead of stdout?

Yes. While the command writes to stdout by default, you can redirect the output to a file using standard shell redirection. For example, run gogcli schema > gogcli-schema.json to save the complete schema. This approach is commonly used in CI/CD pipelines to archive schema files for version tracking or to generate static documentation artifacts.

How do I see hidden commands in gogcli?

To reveal hidden commands and flags that are normally suppressed from the standard schema output, append the --include-hidden flag to your command. For example, run gogcli schema --include-hidden to expose internal implementation details, debugging commands, or experimental features that the CLI developer has marked as hidden in the Kong struct definitions.

What is the current schema version?

The current schema version is 1. This version is hardcoded in the schemaDoc struct within internal/cmd/schema.go and is included in every JSON output as the schema_version field. The version number ensures that consumers of the schema can parse the structure according to a stable contract, even as the gogcli binary evolves in future releases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}