> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# swaig-test

> Test SWAIG functions and generate SWML documents locally without deploying.

[ref-datamap]: /docs/server-sdks/reference/typescript/agents/data-map

The `swaig-test` command loads an agent file and lets you render its SWML, list
its SWAIG functions, execute a function, and simulate serverless environments,
all without deploying. It supports both webhook and [DataMap][ref-datamap]
functions.

```bash
npx swaig-test <agent-path> [options]
```

> **Note**
>
> One action flag is required. A target with no action exits with
> `Error: one of --dump-swml, --list-tools, or --exec is required`. The one
> exception is `--simulate-serverless`, which renders SWML for the platform on
> its own.

## Actions

Choose one action per invocation:

**`--list-tools`** `flag`

List all SWAIG functions registered on the agent, with their parameters.

---

**`--list-agents`** `flag`

List all agents exported from the file. Useful for multi-agent files.

---

**`--dump-swml`** `flag`

Generate and output the full SWML document. Combine with `--raw` for
machine-readable JSON.

---

**`--exec NAME`** `string`

Execute a SWAIG function by name. Pass arguments with `--arg key=value`.

---

**`--parse-only`** `flag`

Validate the command-line arguments, print `parse OK`, and exit without
loading the agent file, touching the filesystem, or making network requests.
`--dry-run` is an alias. Accepted anywhere on the command line, including
after `--exec`.

---

## Common options

**`--raw`** `flag`

Output raw JSON only, suppressing all logs. Designed for piping to `jq`.

---

**`--verbose`** `flag`

Enable verbose output with debug information.

---

**`--format-json`** `flag`

Format output as indented JSON.

---

**`--agent-class`** `string`

Name of the agent class to use when the file exports several.

---

**`--route`** `string`

Override the agent's route.

---

## Function execution options

**`--arg KEY=VALUE`** `string`

A function argument. Repeat for each argument.

---

**`--override KEY=VALUE`** `string`

Override a top-level field in the mock call data (e.g.,
`--override call_state=answered`). Repeatable.

---

## SWML generation options

**`--call-type`** `string` — default: webrtc

Simulated call type: `sip` or `webrtc`.

---

**`--call-direction`** `string` — default: inbound

Simulated call direction: `inbound` or `outbound`.

---

**`--call-state`** `string` — default: active

Simulated call state: `active`, `ringing`, or `hold`.

---

**`--call-id`** `string`

Override the call ID in the mock data.

---

**`--from-number`** `string`

Override the caller's number in the mock data.

---

**`--to-extension`** `string`

Override the destination extension in the mock data.

---

## Serverless simulation

**`--simulate-serverless`** `string`

Render SWML as the agent would on a serverless platform. Valid values:
`lambda`, `gcf`, `azure`, and `cgi`. Any other value exits with an error
naming the supported set.

---

**`--env KEY=VALUE`** `string`

Set an environment variable. Repeatable. Applied after `--env-file`.

---

**`--env-file`** `string`

Load environment variables from a file (one `KEY=VALUE` per line).

---

## Examples

### List tools and generate SWML

```bash
# List all registered SWAIG functions
npx swaig-test src/agent.ts --list-tools

# Generate the SWML document
npx swaig-test src/agent.ts --dump-swml

# Generate raw JSON for piping
npx swaig-test src/agent.ts --dump-swml --raw | jq '.'

# Validate the arguments without loading the agent
npx swaig-test src/agent.ts --parse-only
```

### Execute functions

```bash
# Execute with arguments
npx swaig-test src/agent.ts --exec search --arg query="AI agents" --arg limit=5

# Execute with verbose debug output and an overridden caller number
npx swaig-test src/agent.ts --verbose --exec book_ride \
  --arg pickup="123 Gough Street" \
  --override from=+15551234567
```

### Multi-agent files

```bash
# Discover agents in the file
npx swaig-test src/agents.ts --list-agents

# Target a specific agent by class name
npx swaig-test src/agents.ts --agent-class SalesAgent --list-tools
```

### Serverless simulation

```bash
# AWS Lambda
npx swaig-test src/agent.ts --simulate-serverless lambda

# Google Cloud Functions, with environment variables
npx swaig-test src/agent.ts --simulate-serverless gcf \
  --env SWML_BASIC_AUTH_USER=user \
  --env-file .env
```

## Exit codes

| Code | Meaning                                                      |
| ---- | ------------------------------------------------------------ |
| `0`  | Success                                                      |
| `1`  | Error (file not found, invalid arguments, execution failure) |

> Test SWAIG functions and generate SWML documents locally without deploying.