Index of every page on this site: llms.txt
All skills
mvanhorn avatar

/printing-press

@9e1a8d4
Run it yourself

Set up a new integration, connector, or CLI binding for any API. Wrap or generate a ship-ready Go CLI from an OpenAPI, HAR, or Postman spec via the lean research -> generate -> build -> shipcheck loop. Use when the user says build a CLI, wrap this API, set up a new integration, add a connector, integrate with a service, or names an API by domain.

Use this Skill: https://skilld.dev/gh/mvanhorn/cli-printing-press/printing-press

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesspec-format.md

≈6k tokens on demand. Your agent reads this file only when SKILL.md points to it.

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: string

3. 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, zip

Here --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 cursor

For 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: string

Top-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:

  • name is required
  • source, when set, must be local-sqlite
  • root base_url is required unless base_path is supplied or source: local-sqlite declares an operator-local SQLite source with no HTTP API origin
  • at least one resources entry is required
  • every resource must have at least one endpoint
  • every endpoint must have both method and path
  • resources.<name>.base_url is allowed for resources that live on another host; sub-resources inherit the parent override unless they set their own base_url
  • resources.<name>.endpoints.<name>.base_url is allowed for a single endpoint that lives on another host; it wins over resource and sub-resource overrides
  • resource or endpoint base_url overrides cannot be combined with client_pattern: proxy-envelope, because proxy-envelope clients POST every request to the root base_url
  • flag_name and aliases must 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, root base_url for HTTP specs, resource endpoints, endpoint method, endpoint path)
  • Invalid method values (generator templates only handle GET, POST, PUT, DELETE)
  • Missing path on endpoints
  • Defining body params on GET endpoints (allowed in YAML, but ignored by GET command generation)
  • Forgetting positional: true for 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_url just to make one endpoint work; keep the root API host as the default and use a resource or endpoint base_url override 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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warningstoday3 checks · Risk SAFE
  • Gen Agent Trust Hubtoday

    The skill is a professional-grade development tool for generating Go-based CLIs from API specifications. It implements extensive security controls, including mandatory secret redaction, automated PII scrubbing, and dedicated code review phases that audit generated source code for security and correctness before execution.

  • Sockettoday

    3 alerts: gptAnomaly, gptSecurity

  • Snyktoday

    Risk: MEDIUM · 3 issues

Signed by skilld at 9e1a8d4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 20 hours ago.

Activeupdated 2 weeks ago
What it can do
Runs commands Reads files Edits files Network
version
3.0.0
min-binary-version
4.35.4
created_by
user
All 10 allowed tools
BashReadWriteEditGlobGrepWebFetchWebSearchAskUserQuestionAgent

README badge

README badge for mvanhorn/cli-printing-press/printing-press