appxen 0.2.4

AppXen CLI — manage your MCP Gateway and RAG Engine from the terminal

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

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

Or install from PyPI:

pip install appxen

For local development:

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 under API Keys, then:

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

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:

appxen ingest ./report.pdf

Entire directory (recursive by default):

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

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.

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.

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.

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.

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.

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.

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.

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:

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

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)

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

# 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

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

Ingest only PDFs from a folder

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

Search and get raw JSON for processing

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

Delete all failed sources

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

Use in CI/CD

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"