§ API

Schema · describe

The describe subcommand and --schema flag produce JSON documents that describe a CLI’s structure, capabilities, and output contracts. These are the types that appear in that output.

DescribeOutput

The root type returned by mytool describe.

type DescribeOutput struct {
    Name          string                  // tool binary name
    Summary       string                  // short description
    SchemaVersion string                  // "1.0"
    ToolVersion   string                  // from ToolVersion var or ldflags
    Capabilities  Capabilities
    Profiles      *ProfilesInfo           // nil if no profileable flags
    Commands      []DescribeCommandSchema
}

Capabilities

type Capabilities struct {
    Streaming       bool     // true if WriteEvent / NDJSON is used
    DryRun          bool     // true if --dry-run is supported
    Profiles        bool     // true if profiles are configured
    OutputFormats   []string // e.g. ["json", "ndjson", "text"]
    SchemaVersion   string
    ToolVersion     string
    ProtocolVersion string
}

DescribeCommandSchema

Recursive type: each command contains its subcommands at the same shape.

type DescribeCommandSchema struct {
    Name             string
    Summary          string
    AgentDescription string
    WhenToUse        string
    Idempotent       bool
    Mutating         bool
    Arguments        []ArgumentMetadata
    Flags            []FlagSchema
    Returns          *ReturnSchema
    Examples         []Example
    Subcommands      []DescribeCommandSchema
    Safety           SafetyBlock
}

FlagSchema

type FlagSchema struct {
    Name                  string
    Type                  string   // "string", "int", "bool", "float64", etc.
    Description           string
    Default               any
    Env                   string
    Pattern               string
    Sensitive             bool
    Persistent            bool
    Profileable           bool
    MutuallyExclusiveWith []string
    Enum                  []string
}

SafetyBlock

type SafetyBlock struct {
    ReadOnly    bool `json:"read_only"`
    Idempotent  bool `json:"idempotent"`
    Destructive bool `json:"destructive,omitempty"`
    DryRunnable bool `json:"dry_run_supported,omitempty"`
}

ProfilesInfo

type ProfilesInfo struct {
    Available        []string `json:"available,omitempty"`
    Default          string   `json:"default,omitempty"`
    ProfileableFlags []string `json:"profileable_flags"`
}

Example describe output

shell

$ mytool describe | jq .

json

{
  "name": "mytool",
  "summary": "Document search and indexing tool",
  "schema_version": "1.0",
  "tool_version": "1.0.2",
  "capabilities": {
    "streaming": false,
    "dry_run": false,
    "profiles": true,
    "output_formats": ["json", "text"],
    "schema_version": "1.0",
    "tool_version": "1.0.2",
    "protocol_version": "0.2"
  },
  "profiles": {
    "available": ["dev", "prod"],
    "default": "dev",
    "profileable_flags": ["format", "top"]
  },
  "commands": [
    {
      "name": "query",
      "summary": "Search the index",
      "agent_description": "Search the document index for semantically similar content.",
      "when_to_use": "When the user wants to find documents by meaning.",
      "idempotent": true,
      "mutating": false,
      "flags": [
        {
          "name": "top",
          "type": "int",
          "description": "Number of results to return",
          "default": 10,
          "enum": ["5", "10", "20", "50"],
          "profileable": true
        }
      ],
      "returns": {
        "type": "json",
        "description": "Ranked list of search results",
        "shape": { "path": "string", "score": "float32" }
      },
      "safety": {
        "read_only": true,
        "idempotent": true
      }
    }
  ]
}