CLI Reference

aiml.js ships two command-line tools.

---

aiml-validate

Validate AIML files for syntax errors before loading them into your bot.

Install

npm install -g aiml.js          # global
npx aiml.js aiml-validate ...  # one-off, no install

Usage

aiml-validate [options] <file|directory> [...]

Options:
  -r, --recursive    Recurse into subdirectories
  -s, --stats        Show per-file category count and parse time
  -q, --quiet        Only print errors (suppress warnings)
  --json             Output results as JSON (for CI pipelines)
  -v, --version      Show version
  -h, --help         Show help

Examples

aiml-validate greetings.aiml
aiml-validate ./alice/
aiml-validate -r --stats ./knowledge-base/
aiml-validate --json -r ./aiml/ > report.json   # exits 1 on errors

Sample output

✓ greetings.aiml   (42 categories, 8ms)
✓ personality.aiml (318 categories, 22ms)
✗ broken.aiml
  ✗ error   <category> missing <template> [category]

Results: 3 files checked
  360 categories loaded
  2 valid
  1 with errors (1 total)

---

aiml-serve

Expose any AIML bot as a ChatGPT-compatible REST API with a Swagger UI.

Install

npm install -g aiml.js

Usage

aiml-serve [options] [file|directory ...]

Options:
  -p, --port <n>       Port (default: 8080)
  -m, --model <name>   Model name in API responses (default: aiml-bot-1)
  --api-key <key>      Require Bearer token in Authorization header
  --v2                 Force AIML 2.0 parser
  --rosie              Load bundled Rosie 2.0 bot (needs dev/rosie/)
  --freeaiml           Load bundled Free-AIML bot (needs dev/freeaiml/)
  -h, --help           Show help

Examples

aiml-serve --port 8080 ./alice/
aiml-serve --api-key mysecret ./alice/
aiml-serve --model alice-v1 --rosie --freeaiml

Endpoints

Method	Path	Description
GET	/	API info
GET	/v1/models	List models
POST	/v1/chat/completions	Chat — ChatGPT-compatible
GET	/docs	Swagger UI
GET	/openapi.json	OpenAPI 3.0 spec

Request / response

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"hello"}],"user":"alice"}'

{
  "id": "chatcmpl-aiml.js-4s49pq3j",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "aiml-bot-1",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Hi there!" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 3, "completion_tokens": 3, "total_tokens": 6 }
}

Streaming

Pass "stream": true to receive SSE word-by-word — works with any ChatGPT-compatible client:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"hello"}],"stream":true}'

Use with the OpenAI SDK

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:8080/v1',
  apiKey: 'none',  // or your --api-key value
});

const res = await client.chat.completions.create({
  model: 'aiml-bot-1',
  messages: [{ role: 'user', content: 'hello' }],
  user: 'my-session',  // session ID — bot remembers predicates
});
console.log(res.choices[0].message.content);

Session management

The user field is used as the session ID. Conversations with the same user value share predicate state — the bot remembers names, topics, etc. across requests.

---

Opt-in features

Two template tags are disabled by default for security. Enable them explicitly per bot:

`` — shell execution (Node.js only)

Runs a shell command and inserts stdout into the response.

const bot = new AIML1Bot({ enableSystem: true });

<category>
  <pattern>WHAT TIME IS IT</pattern>
  <template>The time is <system>date +%H:%M:%S</system>.</template>
</category>

⚠️ Only enable for AIML files you fully trust. Disabling it (the default) causes <system> to produce empty output rather than throwing.

`` — inline JS

Evaluates a JS expression with new Function() and returns the result as a string.

const bot = new AIML1Bot({ enableJavaScript: true });

<category>
  <pattern>CALCULATE *</pattern>
  <template><javascript>
    var expr = '<star/>';
    if (/^[0-9+\-*/.() ]+$/.test(expr)) return String(eval(expr));
    return 'Invalid expression.';
  </javascript></template>
</category>

`` — silent logging via subclass

<gossip> fires handleGossip(text) without producing any output. Override it by subclassing:

class LoggingBot extends AIML1Bot {
  protected handleGossip(text: string): void {
    console.log('[gossip]', text);
  }
}