YAML Manifest

One manifest for the CLI, agents, and automations.

Beltline uses a readable YAML manifest to define commands, resources, auth, outputs, confirmations, and exported surfaces — with TypeScript handlers when custom logic is needed.

YAML for the shape. TypeScript for the behavior. No custom language to learn, and one definition beats three wrappers.

The command surface should not be scattered across a dozen files.

Help text lives in one file. API calls live in another. Agent tool descriptions live somewhere else. Automation payloads drift over time. When the same command has different names in the CLI, the MCP server, and the Zapier action, something is wrong with the structure.

Beltline keeps the public shape of the tool in one manifest.

Before and after Beltline

| Before | After Beltline | |--------|----------------| | Command metadata scattered through TypeScript | One readable manifest | | Help text written by hand for every command | Help text generated from the manifest | | MCP schemas maintained as a separate project | MCP schemas generated from the same definitions | | Confirmation rules added ad hoc per command | Shared confirmation rules in one place | | Docs drift from the actual command surface | Reference docs generated alongside the CLI |

One block, three surfaces

# acme.yaml
commands:
  deployments.rollback:
    summary: Roll back a deployment
    input:
      id:
        type: string
        required: true
    confirmation: always
    handler: ./handlers/deployments.rollback.ts
    surfaces:
      cli: true
      mcp: true
      zapier: false

Generated CLI:

acme deployments rollback dep_123 --confirm

Generated MCP tool:

deployments_rollback(id: string)
requires_confirmation: true

The manifest defines the shape. The TypeScript handler in ./handlers/deployments.rollback.ts contains the logic. Each owns its own domain.

What Beltline handles for you

Declarative where it helps Command names, summaries, input schemas, confirmation rules, and surface flags belong in the manifest. They are readable, reviewable, and diffable.

TypeScript where it matters Custom logic, API calls, output formatting, and error handling live in TypeScript handlers. The manifest only tells Beltline where to find them.

Schema-backed editing Add $schema: https://beltline.dev/schema/v1.json and the editor gives autocomplete, inline docs, and validation without any extra tooling.

Command metadata reused across surfaces The same block generates the CLI subcommand, the MCP tool schema, and the automation adapter shape. Change the summary once; all three update.

Designed for teams, not just framework authors Non-framework engineers can add commands by editing the manifest. Code review of the manifest is meaningful and accessible.

Frequently asked questions

Is Beltline a DSL? No. The manifest is standard YAML with a documented JSON Schema. It defines the command shape; custom behavior lives in TypeScript.

Can non-framework engineers add commands? Yes. The manifest makes the most common command additions readable and reviewable without requiring deep framework knowledge.

Can we generate docs from it? Yes. Help text, examples, and reference docs are generated from the manifest and stay in sync automatically.

What if I want to skip the manifest and write TypeScript directly? The manifest is the entry point, but you can keep it minimal and do most work in TypeScript handlers. Beltline stays out of the way of your logic.