Internal YAML Spec Format Reference
Use this format when no OpenAPI spec is available.
1. Complete Schema Reference
# Root object (APISpec)
name: my-api # string (REQUIRED) CLI binary prefix, e.g. "my-api"
description: "My API CLI" # string shown in command help
version: "0.1.0" # string baked into generated binary
source: "" # string optional source archetype; local-sqlite means no HTTP API origin
base_url: "https://api.example.com/v1" # string (REQUIRED unless source: local-sqlite) default base API URL
http_transport: standard # string optional: standard | browser-http | browser-chrome | browser-chrome-h3
health_check_path: "/health" # string optional doctor reachability path; defaults to /
required_headers: # []RequiredHeader optional headers sent on every request
- name: User-Agent
value: "Mozilla/5.0 ..."
auth: # object (AuthConfig)
type: api_key # string: api_key | oauth2 | oauth2_refresh | bearer_token | none
header: "Authorization" # string header name to set
format: "Bearer {token}" # string format template for auth header value
oauth2_grant: device_code # string optional: authorization_code | client_credentials | device_code
device_authorization_url: "https://login.example.com/device" # required for device_code
token_url: "https://login.example.com/token" # OAuth token/refresh endpoint
scopes: ["read"] # []string optional OAuth scopes
default_client_id: "public-client-id" # string optional public OAuth client id
env_vars: # []string env vars used for auth material
- EXAMPLE_API_TOKEN
scheme: bearerAuth # string optional OpenAPI security scheme name
in: header # string optional: header | query | cookie
auth_warnings: # []string optional sniffed-auth rejection notes
config: # object (ConfigSpec). Omit the block to get format toml and path ~/.config/<name>-pp-cli/config.toml
format: toml # string config format: toml | yaml | json. Empty defaults to toml. A non-empty value is kept
path: "~/.config/my-api/config.toml" # string config file path. Empty defaults to ~/.config/<name>-pp-cli/config.<format>, using the final CLI name after --name
learn: # object (LearnConfig) per-CLI vocabulary for the default-on learn loop
disabled: false # bool generation-time opt-out; the authoritative off switch (enabled: false is a no-op once the loop is default-on; disabled: true with an explicit enabled: true is rejected at parse time)
ticker_patterns: # []string Go regexes recognizing ID-shaped tokens in free-text queries; each must compile; must not match ordinary query-family words in seeded playbook examples (greedy ^[a-z0-9]{2,12}$ is rejected); anchor with ^...$
- "^ew-[a-z0-9]+$"
stopwords: # []string domain filler words merged with the built-in English set; whitespace-only entries dropped at parse time
- widget
synonyms: # map[string]string same-referent variant -> canonical phrasing folds; lowercase, single-hop (chains rejected)
"most recent": "latest"
entity_lookup_seeds: # map[string][]LookupSeed keyed by entity kind; canonical must match upstream API responses exactly
widget_series:
- canonical: Example Widget Series Alpha # string (required, non-empty)
aliases: [alpha, series a] # []string alternate strings agents type for the same entity
resources: # map[string]Resource (REQUIRED: at least one key)
users: # resource key becomes top-level command: <name>-cli users
description: "Manage users" # string resource help text
base_url: "https://directory.example.com/v1" # string optional override for this resource and inherited sub-resources
endpoints: # map[string]Endpoint (REQUIRED: at least one key)
list: # endpoint key becomes subcommand: users list
method: GET # string (REQUIRED) must be one of GET | POST | PUT | DELETE
path: "/users" # string (REQUIRED) API path; supports {param} placeholders
mutation: true # bool optional; true marks a GET action as state-changing; false marks a POST/search/list endpoint as a read so the command prints the response body
base_url: "https://search.example.com/v1" # string optional override for this endpoint only
description: "List users" # string endpoint help text
example: " my-api-pp-cli users list --limit 25" # string optional Cobra Example override; include Cobra help indentation
happy_args: "--limit=25" # string optional live-dogfood fixture args
params: # []Param query/path parameters
- name: limit # string upstream wire key; request serialization always uses this value
flag_name: page-size # string optional public CLI/MCP/docs name; agent-authored from evidence
aliases: [] # []string optional hidden compatibility flag spellings
type: int # string type: string | int | bool | float
required: false # bool whether Cobra marks the flag required
positional: false # bool true => consumes positional CLI arg and fills {name} in path
default: 100 # native client flag default; sent when the flag is omitted. OpenAPI optional schema defaults are recorded as server_default and shown in help, but CLI and MCP omit them unless the caller sets the value.
description: "Max results" # string flag description
fields: [] # []Param nested fields for object-like params
enum: [] # []string optional enum hints/constraints
format: "" # string optional format hint (date-time, email, uri, etc.)
- name: cursor # string query parameter --all sends the next cursor back on
type: string
description: "Opaque page cursor"
body: # []Param request body fields, or object schema with properties
- name: email
# flag_name and aliases are optional here too; omit unless evidence supports them
type: string
required: true
positional: false
default: null
description: "User email"
fields: []
enum: []
format: email
# Alternative object-schema form for richer JSON bodies:
# body:
# properties:
# query:
# type: string
# required: true
# variables:
# type: object
# serializerSettings:
# type: object
# properties:
# includeNulls:
# type: bool
# queries:
# type: array
# items:
# type: object
# properties:
# query:
# type: string
response: # object (ResponseDef)
type: array # string response shape: object | array
item: User # string type name referenced from `types`
pagination: # object (Pagination) optional
type: cursor # string pagination style: cursor | offset | page_token
cursor_field: cursor # string response field containing the next cursor; omitted cursor_param is filled from a matching query parameter
has_more_field: data.has_more # string response field indicating more results
response_format: json # string optional: json | csv | html | binary; defaults to json
html_extract: # object optional, only with response_format: html
mode: page # string optional: page | links | embedded-json
link_prefixes: [] # []string optional for links; path-segment-anchored prefixes
script_selector: "" # string optional for embedded-json; defaults to script#__NEXT_DATA__
json_path: "" # string optional for embedded-json; empty returns the full JSON
response_path: data # string optional path to extract list payload from wrapper response
types: # map[string]TypeDef named response/body models
User: # type name referenced by response.item
fields: # []TypeField
- name: user_id # string field name
type: string # string field type (typically string/int/bool/float)Cursor pagination needs a request parameter. cursor_field and
next_cursor_path name the response field that carries the next page token.
cursor_param is the query parameter --all sends that token back on. When
type is cursor or page_token, or type is omitted but a response cursor
path is set, and cursor_param is omitted, generation fills cursor_param
from the endpoint's declared query parameters: the cursor field's leaf when it
matches a query parameter (offset, cursor, endCursor), or, for a
single-segment cursor-like field such as next_cursor, the endpoint's only
cursor-shaped query parameter (for example pagination_cursor). A dotted path
such as pageInfo.endCursor is not mapped onto a differently named query
parameter such as after. If no request parameter can be determined,
generation fails and names the endpoint. An explicit cursor_param is left
unchanged. offset and page pagination are not inferred this way.
learn: is the sanctioned home for per-CLI domain vocabulary. The learn
loop is emitted by default for every print; the generated internal/learn
package stays domain-neutral, so seeds, ticker patterns, synonyms, and
stopwords enter only through this block (or its x-learn OpenAPI
equivalent). Empty seeds parse fine but cap recall at exact-match. For
field-by-field sourcing guidance, a worked example, and the local validation
workflow, see
docs/SPEC-LEARN-AUTHORING.md.
For OAuth2 refresh-token rotation without an interactive browser flow, use
auth.type: oauth2_refresh with auth.token_url. When env_vars is omitted,
the generator defaults to <API>_CLIENT_ID, <API>_CLIENT_SECRET, and
<API>_REFRESH_TOKEN; access tokens are refreshed automatically before API
calls.
response_format must be one of json, csv, html, or binary. Use json
when the response body is JSON and can be parsed directly. Use html only for
GET/HEAD HTML documents, including HTML pages with embedded JSON such as
Next.js __NEXT_DATA__ or schema.org JSON-LD; prefer html_extract modes
page, links, or embedded-json before writing custom extraction code. Use
csv for CSV responses that novel commands may parse through
cliutil.ParseCSV, and binary for opaque byte payloads.
example and happy_args are endpoint-command fixtures. Set example
when the synthesized Cobra example would omit domain-specific context. Use the
exact command string that should appear in --help; lead with two spaces for
Cobra help indentation and include the generated binary name and command path.
When an endpoint is also promoted as a top-level command, the same example
value is used verbatim for both forms, so write it as the promoted invocation
if that is the command users should run. The generator synthesizes runnable
Example: strings and pp:happy-args from parameter example, enum,
default, and format when every required input is derivable, and omits
placeholder example-value Example lines rather than shipping copy-paste 400s.
Set happy_args only when live dogfood needs realistic arguments that cannot
be inferred from those schema hints (opaque IDs, coordinates with no example,
and similar). The value is copied into the generated pp:happy-args
annotation and follows the runtime grammar. Tokens are separated by unescaped
semicolons, so a literal semicolon uses \; (or \\; inside a YAML
double-quoted string). Positional tokens may use <label>=value or
label=value. Positional and flag tokens replace matching synthesized
or Example-derived values, and bare --flag tokens become boolean
--flag=true. Negative numeric flag values use the safe
--flag=-12.3 form. Examples include "--zip=60614" and
"id=example-id;--query=example". When no portable fixture can exist
(continuation cursors, account-specific paths, resource URLs), declare the flag
as --flag=example-value: live dogfood records that endpoint as
blocked-fixture on any flag name instead of failing it, while a real value
that fails still counts as a failure.
html_extract.link_prefixes are path-segment anchored. In mode: links, a
prefix such as /items keeps links whose path is exactly /items or starts
with /items/. It does not keep /items123.html, /items-archive, or other
same-string-prefix leaf paths where the next character is not /.
The one exception is /@, which uses simple string-prefix matching so
social-media-style handle paths such as /@alice and /@bob are kept.
To keep all links under a subtree regardless of the leaf segment shape, choose
the parent directory as the prefix. For paths like /items/123.html and
/items/456.html, use link_prefixes: ["/items"]. Do not use a partial leaf
prefix such as /items/1 unless the target path is exactly /items/1 or has a
slash boundary after it.
types.X.fields is a list, not a map. Each field is an item with
- name: <field-name> followed by type:, description:, and other field
metadata. Map shape such as field-name: {type: string} fails to parse with
cannot unmarshal !!map into []spec.TypeField.
2. Annotated Example (testdata/stytch.yaml)
name: stytch # CLI binary prefix => stytch-cli
description: "Stytch authentication API CLI" # Root help text and README summary
version: "0.1.0" # Printed by `stytch-cli version`
base_url: "https://api.stytch.com/v1" # Default base URL endpoint paths are joined against
health_check_path: "/sessions" # Optional doctor reachability path; omit to probe /
auth:
type: api_key # Uses API key style auth
header: "Authorization" # Header key set on outgoing requests
format: "Basic {project_id}:{secret}" # Expected auth value format
env_vars:
- STYTCH_PROJECT_ID # Credential source env var #1
- STYTCH_SECRET # Credential source env var #2
config:
format: toml # Generated config struct tags use TOML
path: "~/.config/stytch-cli/config.toml" # Default config file location
resources:
users: # Creates `stytch-cli users ...`
description: "Manage Stytch users"
endpoints:
list: # Creates `stytch-cli users list`
method: GET # Generates a query-parameter style command
path: "/users"
description: "List all users"
params:
- name: limit # Exposed as `--limit`
type: int
default: 100 # Default flag value
description: "Max users to return"
- name: cursor # Exposed as `--cursor`
type: string
description: "Pagination cursor"
response:
type: array # Command expects a list-like response
item: User # Rows map to `types.User`
pagination:
type: cursor # Enables cursor pagination helpers
cursor_field: "cursor" # Response path. Omitted cursor_param is filled from the matching cursor query parameter above.
has_more_field: "results.has_more" # Field used to detect continuation
get: # Creates `stytch-cli users get <user_id>`
method: GET
path: "/users/{user_id}" # Placeholder filled from positional arg
description: "Get a user by ID"
params:
- name: user_id
type: string
required: true
positional: true # Required so CLI arg is mapped into `{user_id}`
description: "User ID"
response:
type: object
item: User
create: # Creates `stytch-cli users create --email ...`
method: POST # Generates body-field flags
path: "/users"
description: "Create a new user"
body:
- name: email
type: string
description: "User email"
- name: phone_number
type: string
description: "User phone number"
response:
type: object
item: User
delete: # Creates `stytch-cli users delete <user_id>`
method: DELETE
path: "/users/{user_id}"
params:
- name: user_id
type: string
required: true
positional: true
description: "User ID"
sessions: # Creates `stytch-cli sessions ...`
description: "Manage user sessions"
endpoints:
list: # Creates `stytch-cli sessions list --user_id ...`
method: GET
path: "/sessions"
description: "List sessions for a user"
params:
- name: user_id
type: string
required: true
description: "User ID"
response:
type: array
item: Session
revoke: # Creates `stytch-cli sessions revoke --session_id ...`
method: POST
path: "/sessions/revoke"
description: "Revoke a session"
body:
- name: session_id
type: string
required: true
description: "Session ID to revoke"
types:
User: # Referenced by response.item: User
fields:
- name: user_id
type: string
- name: email
type: string
- name: phone_number
type: string
- name: status
type: string
- name: created_at
type: string
Session: # Referenced by response.item: Session
fields:
- name: session_id
type: string
- name: user_id
type: string
- name: started_at
type: string
- name: expires_at
type: string3. Public Parameter Names
name is the upstream wire key by default and the parameter's public identity
when no override is set. The generator uses it for path substitution and, unless
url_name or body_name says otherwise, query strings and request-body keys.
Do not change name just to make a prettier CLI.
url_name is an optional query-string wire override. Use it when the CLI/MCP
input should keep the name spelling but the URL key must differ.
body_name is an optional request-body wire override. Use it when the CLI/MCP
input should keep the name spelling but the JSON, form, or multipart body key
must differ.
flag_name is the preferred public name shown in generated CLI flags, examples,
typed MCP schemas, and tools-manifest.json. Add it only when source evidence
makes the meaning clear. Valid values are lowercase kebab-case.
aliases are accepted Cobra flag spellings for compatibility. They bind to the
same backing variable as flag_name and are hidden from generated help. Do not
copy raw wire keys into aliases unless they are already valid lowercase
kebab-case public flags.
Example:
params:
- name: s
flag_name: address
aliases: [s]
type: string
required: true
description: Street address
- name: c
flag_name: city
aliases: [c]
type: string
required: true
description: City, state, zipHere --address and --city are the generated public names, --s and --c
remain compatibility aliases, and requests still send upstream keys s and c.
For body fields where the public cursor name and accepted body key diverge,
keep the public identity in name and set body_name to the observed wire key:
body:
- name: startAfter
body_name: searchAfter
type: array
description: Pagination cursorFor richer JSON bodies, body may instead be an object schema with
properties. The parser accepts either body.properties directly or a
body.schema.properties wrapper when copying from OpenAPI-like notes:
body:
properties:
query:
type: string
required: true
description: GraphQL document
variables:
type: object
description: GraphQL variables JSON
serializerSettings:
type: object
properties:
includeNulls:
type: bool
queries:
type: array
items:
type: object
properties:
query:
type: stringTop-level scalars become typed flags. Object properties with their own
properties become nested, parent-prefixed flags. Object and array properties
without expandable scalar children remain JSON-string flags so the command can
pass nested payloads without hand-written Go.
When the request-body schema is a single object property whose value is an
object (the resource root, e.g. {"issue":{"notes":"..."}}), generated
create/update/patch/post commands wrap the constructed field map under that
schema key. Keep the wrapper in the schema when the API requires it. A flat
schema ({"user_id": 1} or {id, name, ...}) stays a flat body — do not
invent a wrap key or flatten a named resource root away. --stdin still sends
the caller's JSON as-is.
4. Validation Rules
Validation in spec.Validate() enforces:
nameis requiredsource, when set, must belocal-sqlite- root
base_urlis required unlessbase_pathis supplied orsource: local-sqlitedeclares an operator-local SQLite source with no HTTP API origin - at least one
resourcesentry is required - every resource must have at least one endpoint
- every endpoint must have both
methodandpath resources.<name>.base_urlis allowed for resources that live on another host; sub-resources inherit the parent override unless they set their ownbase_urlresources.<name>.endpoints.<name>.base_urlis allowed for a single endpoint that lives on another host; it wins over resource and sub-resource overrides- resource or endpoint
base_urloverrides cannot be combined withclient_pattern: proxy-envelope, because proxy-envelope clients POST every request to the rootbase_url flag_nameandaliasesmust be lowercase kebab-case, non-empty when present, and collision-free within their command surface
5. Common Mistakes
These commonly cause generation/build failures or incorrect CLI behavior:
- Missing required fields (
name, rootbase_urlfor HTTP specs, resource endpoints, endpointmethod, endpointpath) - Invalid
methodvalues (generator templates only handleGET,POST,PUT,DELETE) - Missing
pathon endpoints - Defining
bodyparams onGETendpoints (allowed in YAML, but ignored by GET command generation) - Forgetting
positional: truefor params used in/{path_placeholders} - Using parameter types outside supported scalar set:
string,int,bool,float - Putting a website/feed host in the root
base_urljust to make one endpoint work; keep the root API host as the default and use a resource or endpointbase_urloverride for the outlier surface
5. Type Mapping
| YAML Type | Go Type | Cobra Flag | Zero Value |
|---|---|---|---|
string |
string |
StringVar |
"" |
int |
int |
IntVar |
0 |
bool |
bool |
BoolVar |
false |
float |
float64 |
Float64Var |
0.0 |