swaig-test

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

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

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

stringDefaults to webrtc

Simulated call type: sip or webrtc.

--call-direction

stringDefaults to inbound

Simulated call direction: inbound or outbound.

--call-state

stringDefaults to 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

# 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

# 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

# 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

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