docs/reference/cli.md

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



```bash

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**:



```bash

$ 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:

```dotenv

SYNC_EVERY_HOURS=24  # Check every 24 hours

```

### ai_agent sync



Manually synchronize the software catalog and rebuild the index.



```bash

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. 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**:



```bash

$ 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`:

```bash

ai_agent chat   # Works

ai-agent chat   # Also works



ai_agent sync   # Works

ai-agent sync   # Also works

```

## Common Usage Patterns

### Development Workflow

```bash

# Edit catalog

vim dataset/catalog.jsonl



# Sync catalog

ai_agent sync



# Test changes

ai_agent chat

```

<!-- ### Production Deployment

```bash

# In your deployment script:

ai_agent sync                    # Ensure index is built

nohup ai_agent chat &           # Run in background

```

Or use environment variable control:

```bash

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](environment.md)).

## Exit Codes

- **0**: Success
- **1**: General error (see logs)

## Troubleshooting

### Command Not Found

If you see `command not found: ai_agent`:

```bash

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

```bash

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

```bash

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

```bash

# Check artifacts directory

ls -lh artifacts/rag_index/



# Rebuild manually

rm -rf artifacts/rag_index/

ai_agent sync

```

## Next Steps

- Configure [Environment Variables](environment.md)
- Review the [Changelog](changelog.md)
- Return to [Getting Started](../getting-started/quickstart.md)