Quickstart

The shortest possible path from "I want to wrap an API" to a working godmode <my-thing> api ... invocation.

1. The minimum manifest

In an empty folder, create one file:

# my-petstore/manifest.yaml
name: my-petstore
description: My local copy of the Pet Store sample
interfaces:
  api:
    spec: https://petstore3.swagger.io/api/v3/openapi.json
    url: https://petstore3.swagger.io/api/v3

That's it — no package.json, no build step. A single YAML file in a folder is a valid extension.

2. Install from disk

godmode ext install ./my-petstore

godmode reads the manifest, fetches the OpenAPI spec, parses the routes, and registers the extension. The resolved spec is cached at ~/.godmode/extensions/my-petstore.json.

3. Verify discovery

godmode my-petstore --help
godmode my-petstore api --help
godmode my-petstore api pet --help

The --help ladder (reference) walks you from the extension overview down to per-resource operations — all derived from the spec.

4. Fire a request

godmode my-petstore api GET pet 1

If the spec is reachable and the upstream API is up, you'll see the JSON response. If the upstream needs auth, godmode would have shown that in --help; this one doesn't.

5. Iterate

Edit manifest.yaml, then re-register:

godmode ext update my-petstore     # re-fetches the spec, rebuilds the cache

That's the full inner loop. See Local development for the watch-on-edit workflow and how to debug a malformed spec.

What's next

• Manifest schema — every field you can put in manifest.yaml.
• Interface types — when to pick api, graphql, or mcp.
• Auth types — adding an auth: block (bearer, api-key, basic).
• Publishing — turning the folder into a publishable npm package.