Agentlang CLI

A powerful command-line interface for building, running, and managing Agentlang applications

Agentlang is a programming abstraction designed for building reliable AI Agents and Agentic apps. This CLI provides a complete toolkit for developing, testing, and deploying Agentlang applications.

Table of Contents

• Features
• Installation
• Quick Start
• Commands
  • init
  • run
  • repl
  • doc
  • parseAndValidate
  • ui-gen
  • studio
• Configuration
• Examples
• License

Features

• 🚀 Project Initialization - Scaffold new Agentlang applications with proper structure
• ▶️ Runtime Execution - Run Agentlang programs with full runtime support
• 🔄 Interactive REPL - Test and debug with hot-reloading support
• ✅ Validation - Parse and validate Agentlang code for syntax and semantic correctness
• 📚 API Documentation - Auto-generate OpenAPI/Swagger docs from your modules
• 🎨 UI Generation - Generate complete React + TypeScript + Vite frontend for your agentlang app (uses Claude AI)
• 🎨 Design Studio - Visual editor for designing Agents, Data Models, and Workflows locally

Installation

Prerequisites

• Node.js 20.0.0 or higher
• npm, pnpm, or yarn

Global Installation

npm install -g @agentlang/cli

Using pnpm

pnpm install -g @agentlang/cli

Using yarn

yarn global add @agentlang/cli

After installation, the agent command will be available globally.

Quick Start

# 1. Initialize a new Agentlang application
agent init MyApp

# 2. Navigate to your project
cd MyApp

# 3. Add your application logic to src/core.al
# (Edit src/core.al with your entities, events, and relationships)

# 4. Run your application
agent run

# 5. Start interactive REPL with hot-reload
agent repl --watch

# 6. Generate API documentation
agent doc --outputHtml docs/api.html

Commands

init

Initialize a new Agentlang application with the necessary project structure.

agent init <appname>

Arguments:

• <appname> - Name of the application to initialize (required)

What it creates:

• package.json with your app name and version 0.0.1
• config.al for application configuration
• src/core.al with your application module

Examples:

# Initialize a car dealership application
agent init CarDealership

# Initialize an e-commerce app
agent init MyShop

# Initialize with PascalCase for multi-word names
agent init InventoryManagement

Behavior: The command intelligently checks if a directory is already initialized by looking for existing package.json or .al files (excluding config.al). If found, it skips initialization to prevent overwriting your work.

run

Load and execute an Agentlang module with full runtime support.

agent run [file]

Arguments:

• [file] - Path to Agentlang source file or directory (default: current directory)

Options:

• -c, --config <file> - Path to configuration file

Examples:

# Run module in current directory
agent run

# Run specific module file
agent run ./my-app/main.al

# Run with custom configuration
agent run ./my-app -c config.json

# Run module from specific directory
agent run ~/projects/erp-system

What it does: Loads and executes your Agentlang module, starting the runtime environment and initializing all configured services, databases, and integrations. The application will start an HTTP server (default port: 8080) exposing REST APIs for your entities and workflows.

repl

Start an interactive Read-Eval-Print Loop environment for testing and debugging.

agent repl [directory]

Arguments:

• [directory] - Application directory (default: current directory)

Options:

• -w, --watch - Watch for file changes and reload automatically
• -q, --quiet - Suppress startup messages

Examples:

# Start REPL in current directory
agent repl

# Start REPL in specific directory
agent repl ./my-app

# Start with file watching enabled
agent repl --watch

# Start in quiet mode
agent repl --quiet

# Combine options for development workflow
agent repl . --watch

Features:

• Execute Agentlang expressions in real-time
• Test entity operations and workflows
• Hot reload with --watch flag for rapid development
• Access all loaded entities and functions

doc

Generate API documentation in OpenAPI/Swagger format.

agent doc [file]

Arguments:

• [file] - Path to Agentlang source file or directory (default: current directory)

Options:

• -h, --outputHtml <file> - Generate HTML documentation
• -p, --outputPostman <file> - Generate Postman collection

Examples:

# Generate OpenAPI spec (outputs to console)
agent doc

# Generate HTML documentation
agent doc --outputHtml api-docs.html

# Generate Postman collection
agent doc --outputPostman collection.json

# Generate both HTML and Postman
agent doc -h docs.html -p collection.json

# Generate docs for specific module
agent doc ./my-api -h api.html

Generated Endpoints:

For each entity in your module:

• POST /api/{module}/{entity} - Create entity
• GET /api/{module}/{entity} - List entities
• PUT /api/{module}/{entity}/{id} - Update entity
• DELETE /api/{module}/{entity}/{id} - Delete entity

For relationships:

• POST /api/{module}/{entity}/{relationship}/{relatedEntity} - Create related entity
• GET /api/{module}/{entity}/{relationship}/{relatedEntity} - List related entities
• PUT /api/{module}/{entity}/{relationship}/{relatedEntity}/{id} - Update related entity
• DELETE /api/{module}/{entity}/{relationship}/{relatedEntity}/{id} - Delete related entity

parseAndValidate

Parse and validate Agentlang source code for syntax and semantic correctness.

agent parseAndValidate <file>

Arguments:

• <file> - Path to Agentlang source file (required)

Options:

• -d, --destination <dir> - Output directory for generated files

Examples:

# Validate a source file
agent parseAndValidate ./src/main.al

# Parse and validate with output directory
agent parseAndValidate main.al -d ./out

# Validate in CI/CD pipeline
agent parseAndValidate app.al && npm run deploy

Use Cases:

• Pre-deployment validation
• CI/CD pipeline integration
• Syntax checking during development

ui-gen

Generate a complete React + TypeScript + Vite application from a UI specification using Claude AI.

agent ui-gen [spec-file]

Arguments:

• [spec-file] - Path to ui-spec.json (auto-detects if omitted)

Options:

• -d, --directory <dir> - Target directory (default: current directory)
• -k, --api-key <key> - Anthropic API key (or set ANTHROPIC_API_KEY env var)
• -p, --push - Automatically commit and push changes to git
• -m, --message <text> - User message for incremental updates

API Key Setup:

You can provide the Anthropic API key in two ways:

1. Environment variable (recommended):

export ANTHROPIC_API_KEY=sk-ant-...
agent ui-gen

2. Command flag:

agent ui-gen --api-key sk-ant-...

Get your API key at: https://console.anthropic.com

Examples:

# Basic usage - auto-detect spec file
agent ui-gen

# Use specific spec file
agent ui-gen ui-spec.json

# Generate with custom directory
agent ui-gen -d ./my-project

# With API key and git push
agent ui-gen ui-spec.json -k sk-ant-... -p

# Incremental update with user message
agent ui-gen -m "Add dark mode support"

# Update and push to git
agent ui-gen -m "Fix login form validation" -p

Generation Modes:

The UI generator intelligently selects the appropriate mode:

• Fresh Generation - No existing ui/ directory → generates complete application
• Incremental Update - Existing ui/ directory → adds missing files based on spec
• User-Directed Update - Using -m flag → makes targeted changes per instructions

Generated Application Features:

• React 18+ with TypeScript
• Vite for fast development and builds
• Authentication (login, signup, forgot password)
• Entity CRUD operations with forms and validation
• Dashboard with charts and statistics
• Relationship management between entities
• Workflow/event execution
• Responsive, mobile-friendly design
• Mock data mode for testing without backend
• Environment-based configuration

UI Spec Format:

The generator expects a JSON file with the following structure:

{
  "appInfo": {
    "name": "my-app",
    "title": "My Application",
    "description": "Application description"
  },
  "entities": [
    {
      "name": "Customer",
      "displayName": "Customers",
      "fields": [
        {
          "name": "name",
          "type": "string",
          "required": true
        },
        {
          "name": "email",
          "type": "string",
          "required": true
        }
      ]
    }
  ],
  "relationships": [],
  "workflows": [],
  "navigation": {
    "groups": []
  }
}

Authentication Endpoints:

The generated application uses the following endpoints:

• POST /agentlang_auth/login - User login
• POST /agentlang_auth/signUp - User registration
• POST /agentlang_auth/forgotPassword - Password recovery

Environment Configuration:

Generated .env file:

VITE_BACKEND_URL=http://localhost:8080/
VITE_USE_MOCK_DATA=true

By default, mock data mode is enabled for immediate testing. Set VITE_USE_MOCK_DATA=false when your backend is ready.

studio

Start the Agentlang Design Studio locally for visual editing of your project.

agent studio [path]

Arguments:

• [path] - Path to Agentlang project directory (default: current directory)

Options:

• -p, --port <port> - Port to run Studio server on (default: 4000)

What it does:

The studio command starts a local development environment that includes:

1. Agentlang Server - Runs your Agentlang application in the background (via agent run)
2. Studio UI - Serves the visual Design Studio interface
3. File System Access - Provides API endpoints for reading and writing project files

Prerequisites:

Install @agentlang/lstudio as a development dependency in your project:

npm install --save-dev @agentlang/lstudio

The command will automatically find @agentlang/lstudio from:

• Your project's node_modules (if installed locally)
• Agentlang CLI's node_modules (fallback)

Examples:

# Start Studio in current directory
agent studio

# Start Studio for specific project
agent studio ./my-project

# Start Studio on custom port
agent studio --port 5000

# Combine path and port options
agent studio ./monitoring -p 5000

Features:

• Visual Editor - Design Agents, Data Models, and Workflows visually
• Live File Sync - Changes made in Studio are saved directly to your .al files
• Auto Browser - Automatically opens your default browser to the Studio UI
• Background Server - Agentlang API server runs in the background (default port: 8080)
• Hot Reload - File changes are reflected immediately

Usage Workflow:

# 1. Navigate to your Agentlang project
cd my-agentlang-app

# 2. Ensure @agentlang/lstudio is installed
npm install --save-dev @agentlang/lstudio

# 3. Start the Studio
agent studio

# 4. Browser opens automatically at http://localhost:4000
# 5. Edit your project visually in the Studio UI
# 6. Changes are saved directly to your source files

Ports:

• Studio UI: Default port 4000 (configurable with --port)
• Agentlang API: Default port 8080 (configured in config.al)

Troubleshooting:

If you see "Failed to find @agentlang/lstudio":

# Install it in your project
npm install --save-dev @agentlang/lstudio

# Or install it globally in agentlang-cli
cd /path/to/agentlang-cli
npm install @agentlang/lstudio

Configuration

The CLI supports configuration through a config.al or custom configuration file.

Basic Configuration

// config.al or app.config.js
{
  "service": {
    "port": 8080
  },
  "store": {
    "type": "sqlite",
    "dbname": "myapp.db"
  }
}

Database Options

SQLite (Default)

{
  "store": {
    "type": "sqlite",
    "dbname": "myapp.db"  // optional, defaults to in-memory
  }
}

PostgreSQL

{
  "store": {
    "type": "postgres",
    "host": "localhost",
    "username": "postgres",
    "password": "postgres",
    "dbname": "myapp",
    "port": 5432
  }
}

Advanced Configuration

{
  "service": {
    "port": 8080
  },
  "store": {
    "type": "postgres",
    "host": "localhost",
    "username": "postgres",
    "password": "postgres",
    "dbname": "myapp",
    "port": 5432
  },
  "graphql": {
    "enabled": true
  },
  "rbacEnabled": true,
  "auditTrail": {
    "enabled": true
  },
  "authentication": {
    "enabled": true
  }
}

Examples

Simple Agentlang Module

module UserManagement {
  entity User {
    id: UUID
    name: String
    email: String
    createdAt: DateTime
  }

  event UserCreated {
    userId: UUID
    timestamp: DateTime
  }
}

Complete Development Workflow

# 1. Initialize a new Agentlang application
mkdir my-project && cd my-project
agent init MyApp

# 2. Navigate into the project
cd MyApp

# 3. Add your application logic to src/core.al
# (Edit src/core.al with your entities and logic)

# 4. Test interactively with REPL
agent repl --watch

# 5. Run your Agentlang application
agent run

# 6. Generate API documentation
agent doc -h ./docs/api.html

# 7. Generate UI from specification
export ANTHROPIC_API_KEY=sk-ant-...
agent ui-gen ui-spec.json -p

# 8. Navigate to generated UI and test
cd ui
npm install
npm run dev

# 9. Make iterative updates to UI
cd ..
agent ui-gen -m "Add export to CSV feature"

CI/CD Integration

# In your CI/CD pipeline
agent parseAndValidate src/main.al
if [ $? -eq 0 ]; then
  echo "Validation successful"
  agent run src/main.al
else
  echo "Validation failed"
  exit 1
fi

E-Commerce Example

# Initialize e-commerce app
mkdir online-store && cd online-store
agent init OnlineStore
cd OnlineStore

# Start REPL with hot-reload for development
agent repl --watch

# In another terminal, run the application
agent run

# Generate API docs
agent doc -h docs/api-docs.html -p docs/postman-collection.json

# Generate UI
agent ui-gen ui-spec.json --push

File Extensions

The CLI supports Agentlang files with the following extensions:

• .al (recommended)
• .agentlang

Error Handling

The CLI provides clear error messages for common issues:

• Configuration Errors - Invalid configuration files or missing required fields
• Parse Errors - Syntax errors in Agentlang code with line numbers
• Validation Errors - Semantic errors in Agentlang modules
• Runtime Errors - Errors during program execution with stack traces

Development

Building from Source

git clone https://github.com/agentlang/agentlang-cli.git
cd agentlang-cli
npm install
npm run build

Running in Development Mode

npm run dev

Running Tests

npm test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

• Documentation: GitHub Repository
• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

This project is licensed under the Sustainable Use License - see the LICENSE file for details.

Made with ❤️ by the Agentlang Team