Skip to content

CLI Commands

The AI Imaging Agent provides a command-line interface for starting the application and managing the software catalog.

Available Commands

ai_agent chat

Launch the chat-based user interface.

ai_agent chat

What it does:

  1. Performs startup catalog synchronization
  2. Loads the FAISS index
  3. Initializes the retrieval and agent pipelines
  4. Launches the Gradio web interface on http://127.0.0.1:7860
  5. Starts background catalog refresh (if configured)

Options: None (all configuration via .env and config.yaml)

Example:

$ ai_agent chat
[startup-sync] 150 → dataset/catalog.jsonl
[startup-refresh] catalog unchanged; keeping existing FAISS index
Running on local URL:  http://127.0.0.1:7860

To create a public link, set `share=True` in `launch()`.

Background Refresh:

If SYNC_EVERY_HOURS is set in .env, the catalog will auto-refresh in the background:

SYNC_EVERY_HOURS=24  # Check every 24 hours

ai_agent sync

Manually synchronize the software catalog and rebuild the index.

ai_agent sync

What it does:

  1. Loads the software catalog from SOFTWARE_CATALOG path
  2. Embeds all tool descriptions using BGE-M3
  3. Builds FAISS vector index
  4. Extracts vocabulary for query expansion
  5. Saves artifacts to artifacts/rag_index/

When to use:

  • After editing catalog.jsonl
  • After adding new tools
  • To force index rebuild
  • For testing catalog changes

Example:

$ ai_agent sync
[sync] 150 → dataset/catalog.jsonl
[sync] Embedding 150 tools... (5.2s)
[sync] Building FAISS index...
[sync] Saved to artifacts/rag_index/
[sync] Sync complete.

Command Aliases

Both commands are available with either ai_agent or ai-agent:

ai_agent chat   # Works
ai-agent chat   # Also works

ai_agent sync   # Works
ai-agent sync   # Also works

Common Usage Patterns

Development Workflow

# Edit catalog
vim dataset/catalog.jsonl

# Sync catalog
ai_agent sync

# Test changes
ai_agent chat

<!-- ### Production Deployment

# In your deployment script:
ai_agent sync                    # Ensure index is built
nohup ai_agent chat &           # Run in background

Or use environment variable control:

export SYNC_EVERY_HOURS=0       # Disable auto-refresh in production
ai_agent chat
``` -->

### Testing & Development

```bash
# Enable debug logging
export LOGLEVEL_CONSOLE=DEBUG
export LOG_PROMPTS=1
ai_agent chat

Environment Variables

All configuration is via environment variables (see Environment Variables Reference).

Exit Codes

  • 0: Success
  • 1: General error (see logs)

Troubleshooting

Command Not Found

If you see command not found: ai_agent:

# Ensure package is installed
pip install -e .

# Check installation
pip list | grep ai-agent

# Try with python -m
python -m ai_agent.cli chat

Port Already in Use

If port 7860 is occupied:

# Find and kill process
lsof -ti:7860 | xargs kill -9

# Or change port in code (ui/app.py)

Catalog Load Error

If catalog fails to load:

# Verify catalog exists
ls -lh dataset/catalog.jsonl

# Verify JSONL syntax
python -c "import json; [json.loads(l) for l in open('dataset/catalog.jsonl')]"

# Check environment variable
echo $SOFTWARE_CATALOG

Index Build Error

If FAISS index building fails:

# Check artifacts directory
ls -lh artifacts/rag_index/

# Rebuild manually
rm -rf artifacts/rag_index/
ai_agent sync

Next Steps