# What Is the gogcli Schema Command? A Complete Technical Guide

> Explore the gogcli schema command for a machine readable JSON output of all commands, flags, and arguments. Uncover your CLI's full structure.

- Repository: [Peter Steinberger/gogcli](https://github.com/steipete/gogcli)
- Tags: deep-dive
- Published: 2026-02-16

---

**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](https://github.com/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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/steipete/gogcli/blob/main/internal/cmd/schema.go), with registration occurring in [`internal/cmd/root.go`](https://github.com/steipete/gogcli/blob/main/internal/cmd/root.go).

### The SchemaCmd Struct

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

```go
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:

```go
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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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.