CLI Reference

WebPal provides a large number of Artisan console commands for server administration, maintenance, and AI agent management. This reference covers the most commonly used commands.

Run php artisan list to see all available commands. Use php artisan [command] --help for detailed parameter documentation.

---

Content and Compilation

webpal:compile (or site:compile)

Compile the XML-based CMS content into Laravel routes and Blade views. This must be run after editing XML content files in the /Web directory.

php artisan webpal:compile

Output is written to storage/webpal/generated/. Auto-compilation is also triggered on application boot if web.xml has been modified.

---

Queue Workers

WebPal relies on background queue workers for several features. Run these in parallel with the web server.

Standard Queue Worker

php artisan queue:work --queue=default --tries=3 --timeout=600

Console/AI Queue Worker

Required for AI chat functionality:

php artisan queue:work --queue=console --tries=3 --timeout=600

For production, configure Supervisor to keep these workers running persistently. See doc/console-chat-system.md for Supervisor configuration examples.

---

WebSocket Server

reverb:start

Start the WebSocket server (required for real-time updates, AI streaming, HTML preview notifications):

php artisan reverb:start

For development, run in a separate terminal alongside php artisan queue:work. For production, configure as a system service.

---

AI Agent Commands

agent:chats

List all AI conversations with token usage statistics:

php artisan agent:chats

Options:

• --agent= — filter by agent name
• --user= — filter by user
• --limit= — number of conversations to show

agent:conversation-sizes

Show estimated LLM token usage per conversation:

php artisan agent:conversation-sizes

agent:export

Export a custom agent to a portable archive for backup or transfer:

php artisan agent:export my_custom_agent
php artisan agent:export my_custom_agent --output=/path/to/backup/

The archive contains the agent class file, prompt template, and metadata.

agent:import

Import an agent from an archive:

php artisan agent:import my_custom_agent.zip

# Preview without making changes
php artisan agent:import my_custom_agent.zip --dry-run

# Overwrite an existing agent with the same name
php artisan agent:import my_custom_agent.zip --overwrite

vizra:agents

List all discovered and registered agents:

php artisan vizra:agents

vizra:chat

Test an agent interactively from the command line:

php artisan vizra:chat doc_agent

vizra:run:eval

Run the agent evaluation framework:

# Run all evaluations
php artisan vizra:run:eval

# Run a specific evaluation class
php artisan vizra:run:eval CustomerSupportEvaluation

# Run with a specific assertion
php artisan vizra:run:eval --assertion=correctness

# Write results to a JSON file
php artisan vizra:run:eval --output=results.json

vizra:trace

View a specific agent execution trace:

php artisan vizra:trace {traceId}

console-chat:cleanup

Manually clean up idle console AI processes:

php artisan console-chat:cleanup

By default, idle processes are cleaned up automatically every 5 minutes after 30 minutes of inactivity.

---

Email Processing

email:receive

Receive an email from procmail via stdin:

php artisan email:receive --sender="$SENDER" --recipient="$RECIPIENT"

Typical usage in .procmailrc:

:0
| /usr/bin/php /path/to/artisan email:receive --sender="$SENDER"

mailbox:watch

Watch a mailbox file or directory for incoming messages:

# Watch an mbox-format file
php artisan mailbox:watch /var/spool/mail/user --format=mbox

# Watch a Maildir directory
php artisan mailbox:watch /home/user/Maildir --format=maildir

---

Database and Maintenance

migrate

Run all pending database migrations:

php artisan migrate

db:create (webpal db:create)

Create the WebPal database structure:

webpal db:create

tinker

Run PHP code interactively for debugging:

php artisan tinker

# Run a single expression
php artisan tinker --execute "echo App\Models\User::count();"

---

Scheduled Tasks

WebPal has a scheduler that runs periodic maintenance tasks. Ensure the Laravel scheduler is configured in cron:

* * * * * cd /path/to/webpal && php artisan schedule:run >> /dev/null 2>&1

Scheduled tasks include:

• Recycler cleanup — permanently removes files that have been in the recycler beyond the retention period
• Console process cleanup — terminates idle AI console processes
• Thumbnail generation — retries failed thumbnail generation

---

Artisan Commands Reference

Run php artisan list to see the complete list of ~198 available commands. Key categories include:

Prefix	Category
webpal:	WebPal core operations (compile, cleanup, indexing)
agent:	AI agent management
vizra:	Vizra ADK agent framework
email:	Email processing
mailbox:	Mailbox monitoring
console-chat:	AI console chat management
queue:	Queue worker management
reverb:	WebSocket server
migrate	Database migrations
tinker	Interactive PHP REPL
route:list	View all registered routes
config:show	View configuration values
make:	Code generation