Skip to main content

​
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

FlagDescription
--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

FlagDescription
--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
--standaloneGenerate 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