> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Forge Commands

> Guide to using Svantic Forge for generating tools and scaffolding agents from OpenAPI specs, source code, or natural language.

# 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.

```bash theme={null}
svantic forge --help
```

## `svantic forge tool`

Generate tool specifications and TypeScript capability code from various sources.

### From an OpenAPI Spec

```bash theme={null}
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:

```bash theme={null}
svantic forge tool --spec openapi.yaml --pick /tickets,/contacts
```

### Override the Domain Name

```bash theme={null}
svantic forge tool --spec openapi.yaml --domain helpdesk
```

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

### Set the Output Directory

```bash theme={null}
svantic forge tool --spec openapi.yaml --out ./generated
```

### List Operations (Preview)

Preview what an OpenAPI spec contains without generating:

```bash theme={null}
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`):

```bash theme={null}
svantic forge tool --prompt "Zendesk: list, create, update, and triage tickets"
```

Provide documentation for additional context:

```bash theme={null}
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

```bash theme={null}
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`:

```bash theme={null}
svantic forge agent --name zendesk-agent --spec zendesk.yaml --standalone
```

Additional files:

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

After scaffolding:

```bash theme={null}
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:

```bash theme={null}
svantic forge agent --name support-agent --tools zendesk.yaml,hubspot.yaml --standalone
```

### With Description and Port

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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
```