Forge Commands

The svantic forge subcommand generates tool specs and scaffolds agent services from OpenAPI specs or natural language prompts. All forge operations run locally — no mesh connection or authentication is required.

svantic forge --help

`svantic forge tool`

Generate tool specifications and TypeScript capability code from various sources.

From an OpenAPI Spec

svantic forge tool --spec openapi.yaml

This parses the OpenAPI document, converts operations to a Tool Spec YAML, and materializes TypeScript capability and trigger files:

  zendesk v1.0.0 -- 12 tools, 3 triggers
    * list_tickets -- GET /tickets
    * create_ticket -- POST /tickets
    * update_ticket -- PUT /tickets/{id}
    ...

  Spec written: ./zendesk.yaml
  Capabilities: ./zendesk_capabilities.ts
  Triggers: ./zendesk_triggers.ts

Filter with `--pick`

Select specific API paths or function names:

svantic forge tool --spec openapi.yaml --pick /tickets,/contacts

Override the Domain Name

svantic forge tool --spec openapi.yaml --domain helpdesk

Output files become helpdesk.yaml, helpdesk_capabilities.ts, etc.

Set the Output Directory

svantic forge tool --spec openapi.yaml --out ./generated

List Operations (Preview)

Preview what an OpenAPI spec contains without generating:

svantic forge tool --list openapi.yaml

Output:

  Zendesk Support API -- 24 operations

  GET     /tickets                      List all tickets
  POST    /tickets                      Create a ticket
  GET     /tickets/{id}                 Show a ticket
  PUT     /tickets/{id}                 Update a ticket
  DELETE  /tickets/{id}                 Delete a ticket
  ...

  Use --pick to select specific paths:
  svantic forge tool --spec openapi.yaml --pick /tickets,/contacts

From Natural Language (AI-Powered)

Use AI to generate tools from a description (requires GOOGLE_API_KEY):

svantic forge tool --prompt "Zendesk: list, create, update, and triage tickets"

Provide documentation for additional context:

svantic forge tool --prompt "Stripe: charges, refunds, customers" --docs https://stripe.com/docs/api

`forge tool` Flag Reference

Flag	Description
`--spec <file>`	OpenAPI v3 spec (YAML/JSON) or existing Tool Spec YAML
`--list <file>`	List all operations in the spec (no generation)
`--prompt <text>`	AI-powered generation from natural language
`--docs <url>`	Documentation URL for context (use with `--prompt`)
`--pick <names>`	Comma-separated path prefixes or function names to include
`--domain <name>`	Override domain name (default: derived from spec title)
`--out <dir>`	Output directory (default: current directory)

`svantic forge agent`

Scaffold a complete agent service from one or more tool specs.

From a Single Spec

svantic forge agent --name zendesk-agent --spec zendesk.yaml

Output:

  Agent scaffolded: zendesk-agent
    zendesk-agent/
    +-- zendesk.yaml
    +-- zendesk_capabilities.ts
    +-- zendesk_triggers.ts
    +-- server.ts
    +-- .env.example

  Next steps:
    cd zendesk-agent
    cp .env.example .env  # fill in secrets
    npx tsx server.ts

With Full Project Files

Add --standalone to generate package.json, Dockerfile, and tsconfig.json:

svantic forge agent --name zendesk-agent --spec zendesk.yaml --standalone

Additional files:

    +-- package.json
    +-- Dockerfile
    +-- tsconfig.json

After scaffolding:

cd zendesk-agent
npm install
cp .env.example .env
npx tsx server.ts

Compose from Multiple Specs

Combine tools from multiple domains into one agent:

svantic forge agent --name support-agent --tools zendesk.yaml,hubspot.yaml --standalone

With Description and Port

svantic forge agent --name billing-agent --spec stripe.yaml \
  --description "Handles payment processing and invoicing" \
  --port 9200 --standalone

From an OpenAPI Spec Directly

Pass an OpenAPI spec directly — forge converts it automatically:

svantic forge agent --name api-agent --spec openapi.yaml --standalone

`forge agent` Flag Reference

Flag	Description
`--name <name>`	Agent service name (required)
`--spec <file>`	Tool Spec YAML or OpenAPI spec file
`--tools <files>`	Comma-separated spec files for multi-domain compose
`--standalone`	Generate full project scaffolding
`--description <text>`	Agent description override
`--port <number>`	Port override (default: 9100)
`--out <dir>`	Output directory (default: `./<name>/`)

Examples

Generate Tools, Then Scaffold an Agent

# Step 1: inspect the spec
svantic forge tool --list ./specs/zendesk-openapi.yaml

# Step 2: generate tools for the paths you need
svantic forge tool --spec ./specs/zendesk-openapi.yaml --pick /tickets --out ./specs

# Step 3: scaffold a standalone agent
svantic forge agent --name zendesk-agent --spec ./specs/zendesk.yaml --standalone

AI-Powered End-to-End

# Generate tools from a prompt
svantic forge tool --prompt "Jira: list, create, update, transition issues" --domain jira --out ./specs

# Scaffold the agent
svantic forge agent --name jira-agent --spec ./specs/jira.yaml --standalone --port 9300

Compose Multiple Domains

# Generate specs for each domain
svantic forge tool --spec zendesk-openapi.yaml --pick /tickets --out ./specs
svantic forge tool --spec hubspot-openapi.yaml --pick /contacts --out ./specs

# Compose into one agent
svantic forge agent --name crm-agent --tools ./specs/zendesk.yaml,./specs/hubspot.yaml --standalone

​Forge Commands

​svantic forge tool

​From an OpenAPI Spec

​Filter with --pick

​Override the Domain Name

​Set the Output Directory

​List Operations (Preview)

​From Natural Language (AI-Powered)

​forge tool Flag Reference

​svantic forge agent

​From a Single Spec

​With Full Project Files

​Compose from Multiple Specs

​With Description and Port

​From an OpenAPI Spec Directly

​forge agent Flag Reference

​Examples

​Generate Tools, Then Scaffold an Agent

​AI-Powered End-to-End

​Compose Multiple Domains