# AppXen CLI

Command-line tool for managing your AppXen MCP Gateway and RAG Engine. Ingest documents, search your knowledge base, and manage sources — all from the terminal.

## Install

```bash
curl -sSL https://appxen.ai/install.sh | sh
```

Or install from PyPI:

```bash
pip install appxen
```

For local development:

```bash
pip install -e products/appxen-cli/
```

Requires Python 3.10+.

## Quick Start

### 1. Log in with your API key

Get an API key from the [AppXen Console](https://console.appxen.ai) under **API Keys**, then:

```bash
appxen login
```

You'll be prompted for your key (input is hidden). The CLI validates the key format (`axgw_*`) and tests connectivity before saving.

Your key is stored in `~/.config/appxen/config.toml` with `0600` permissions.

### 2. Check connectivity

```bash
appxen status
```

```
Endpoint:  https://api.appxen.ai
Service:   mcp-gateway-pro
Version:   0.1.0
Status:    Connected
RAG:       12 sources, 347 chunks
```

### 3. Ingest documents

Single file:

```bash
appxen ingest ./report.pdf
```

Entire directory (recursive by default):

```bash
appxen ingest ./docs/
```

The CLI uploads each file, then polls until ingestion completes (chunking, embedding, indexing). You'll see progress bars for both stages:

```
Found 14 file(s) to ingest.
  Uploading architecture.pdf ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 14/14
Waiting for 14 file(s) to process...
  Processing architecture.pdf ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 14/14

OK 14 file(s) ingested successfully.
```

### 4. Search

```bash
appxen search "how does authentication work"
```

```
╭──────────── #1 auth-design.md (score: 0.847) ────────────╮
│ Authentication uses passkeys (WebAuthn) as the primary    │
│ method with magic link email as a fallback...             │
╰──────────────────────── chunk: a1b2c3d4-e5f ─────────────╯
╭──────────── #2 api-keys.md (score: 0.723) ────────────────╮
│ API keys use the format axgw_{mode}_{version}_{hex} and   │
│ are stored as SHA-256 hashes in DynamoDB...               │
╰──────────────────────── chunk: f6g7h8i9-j0k ─────────────╯
```

## Commands

### `appxen login`

Save your API key to the local config.

```bash
appxen login                           # default profile, production endpoint
appxen login --profile staging         # named profile
appxen login --endpoint http://localhost:8080   # custom endpoint
```

| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--profile` | `-p` | `default` | Profile name |
| `--endpoint` | `-e` | `https://api.appxen.ai` | Gateway endpoint |

### `appxen status`

Check connectivity, show gateway info and RAG stats.

```bash
appxen status
appxen status --json              # machine-readable output
```

### `appxen ingest <path>`

Upload files to the RAG knowledge base. Accepts a single file or a directory.

```bash
appxen ingest ./report.pdf                    # single file
appxen ingest ./docs/                         # directory (recursive)
appxen ingest ./docs/ --glob "*.md"           # only markdown files
appxen ingest ./docs/ --no-recursive          # top-level only
appxen ingest ./docs/ --no-poll               # upload and exit (don't wait)
appxen ingest ./docs/ --json                  # JSON output (implies --no-poll)
```

| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--glob` | `-g` | `*` | Glob pattern for filtering files in a directory |
| `--recursive / --no-recursive` | | `--recursive` | Recurse into subdirectories |
| `--poll / --no-poll` | | `--poll` | Wait for ingestion to complete |
| `--json` | | `false` | Output raw JSON results |

**Supported file types:**

| Category | Extensions |
|----------|------------|
| Documents | `.pdf` `.docx` `.html` `.htm` `.md` `.txt` `.csv` `.json` `.xml` `.yaml` `.yml` |
| Code | `.py` `.js` `.ts` `.jsx` `.tsx` `.css` `.sql` `.sh` `.rs` `.go` `.java` `.c` `.cpp` `.h` `.rb` `.php` |
| Images (OCR) | `.png` `.jpg` `.jpeg` `.tiff` `.bmp` |

Unsupported file types are silently skipped when scanning directories. The maximum file size is 100 MB.

**Exit codes:**

| Code | Meaning |
|------|---------|
| `0` | All files ingested successfully |
| `1` | Fatal error (no files found, not logged in, etc.) |
| `2` | Partial failure (some files failed) |

### `appxen search <query>`

Semantic search over your knowledge base.

```bash
appxen search "database schema design"
appxen search "error handling" --top-k 10
appxen search "deployment steps" --json
```

| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--top-k` | `-k` | `5` | Number of results to return |
| `--json` | | `false` | Output raw JSON |

### `appxen sources`

List and manage knowledge base sources.

```bash
appxen sources                            # list all sources
appxen sources --status ready             # filter by status
appxen sources --search "report"          # filter by filename
appxen sources --limit 50                 # more results
appxen sources --json                     # JSON output
```

| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--status` | `-s` | | Filter by status (`ready`, `processing`, `queued`, `failed`) |
| `--search` | `-q` | | Filter by filename |
| `--limit` | `-n` | `20` | Results per page |
| `--offset` | | `0` | Pagination offset |
| `--json` | | `false` | Output raw JSON |

```
                          Sources (47 total)
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ ID           ┃ Filename              ┃ Status ┃ Chunks ┃ Created             ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ a1b2c3d4-e5f │ architecture.pdf      │ ready  │     23 │ 2026-02-08T14:30:00 │
│ f6g7h8i9-j0k │ api-reference.md      │ ready  │      8 │ 2026-02-08T14:28:00 │
│ ...          │ ...                   │ ...    │    ... │ ...                 │
└──────────────┴───────────────────────┴────────┴────────┴─────────────────────┘
```

### `appxen sources delete <source_id>`

Delete a source and all its chunks.

```bash
appxen sources delete a1b2c3d4-e5f6-7890-abcd-1234567890ab
appxen sources delete a1b2c3d4-e5f6-7890-abcd-1234567890ab --yes   # skip confirmation
```

| Option | Short | Description |
|--------|-------|-------------|
| `--yes` | `-y` | Skip the confirmation prompt |

### `appxen stats`

Show knowledge base statistics.

```bash
appxen stats
appxen stats --json
```

```
╭──────────────────────── RAG Engine Stats ─────────────────────────╮
│ Sources:  47                                                      │
│ Chunks:   1,203                                                   │
│ Storage:  24.7 MB                                                 │
╰───────────────────────────────────────────────────────────────────╯
```

## Configuration

### Config file

Stored at `~/.config/appxen/config.toml`:

```toml
[default]
api_key = "axgw_live_k1_..."
endpoint = "https://api.appxen.ai"

[staging]
api_key = "axgw_test_k1_..."
endpoint = "https://staging-api.appxen.ai"
```

Switch profiles with `--profile`:

```bash
appxen --profile staging sources
appxen -p staging search "test query"
```

### Environment variables

Environment variables override the config file:

| Variable | Description |
|----------|-------------|
| `APPXEN_API_KEY` | API key (overrides config file) |
| `APPXEN_ENDPOINT` | Gateway endpoint (overrides config file) |
| `APPXEN_PROFILE` | Default profile name (default: `default`) |

```bash
# One-off command against local dev stack
APPXEN_API_KEY=axgw_test_k1_abc123 APPXEN_ENDPOINT=http://localhost:8080 appxen status
```

## JSON Output

Every command supports `--json` for scripting and piping:

```bash
# Get source IDs for all ready sources
appxen sources --json | jq '.sources[] | select(.status == "ready") | .source_id'

# Count chunks across all sources
appxen stats --json | jq '.chunk_count'

# Ingest and capture results
appxen ingest ./docs/ --json | jq '.[] | {file, status, source_id}'
```

## Examples

### Ingest a project's documentation

```bash
appxen ingest ./docs/ --glob "*.md" --recursive
```

### Ingest only PDFs from a folder

```bash
appxen ingest ./reports/ --glob "*.pdf"
```

### Search and get raw JSON for processing

```bash
appxen search "error handling patterns" --top-k 20 --json
```

### Delete all failed sources

```bash
appxen sources --status failed --json \
  | jq -r '.sources[].source_id' \
  | xargs -I{} appxen sources delete {} --yes
```

### Use in CI/CD

```bash
export APPXEN_API_KEY=${{ secrets.APPXEN_API_KEY }}
export APPXEN_ENDPOINT=https://api.appxen.ai

# Sync docs on every deploy
appxen ingest ./docs/ --glob "*.md"
```
