AppXen CLI

One command to install:

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

Or install directly with pip:

pip install appxen

Requires Python 3.10+. The installer prefers pipx for isolated installs.

Create an API key in your appliance's console (https://<your-appliance-host>) under API Keys in the sidebar. The key looks like axgw_live_k1_... and is shown once. Then:

appxen login

In a terminal you are prompted for your key (input is hidden). In a script, pipe it: when stdin is not a terminal, the key is the first line of stdin and nothing is echoed.

printf '%s\n' "$APPXEN_KEY" | appxen login --endpoint https://your-appliance-host

Which endpoint?

The endpoint is your appliance's own origin. The CLI derives the gateway and orchestrator paths from it. By default it is https://localhost: the appliance's own proxy, which is what you reach when you run the CLI on the appliance itself. For your appliance, the endpoint is the ConsoleUrl output of your CloudFormation stack, or your domain after appxenctl set-domain.

# on the appliance itself
appxen login --insecure

# from your own machine
appxen login --endpoint https://your-appliance-host --insecure

appxen login --endpoint https://appliance.example.com

What login does

The CLI checks the key's format (axgw_*), then verifies it with the appliance on an authenticated route. Only a key the appliance accepted is saved. A refused key, or one that could not be verified (the appliance is unreachable, its certificate is refused), is not saved and the command exits 1. For an appliance that cannot be reached yet, appxen login --no-verify saves the key unchecked.

Your key is stored in ~/.config/appxen/config.toml with 0600 permissions, in a directory with 0700.

Exit status of appxen login

Check connectivity and the API key, and show the gateway and RAG stats. The key is verified on an authenticated route, because the gateway's /health answers anyone.

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

CLI:       0.2.7
Endpoint:  https://localhost
Service:   mcp-gateway-pro
Gateway:   0.1.0
Status:    Connected
RAG:       12 sources, 347 chunks

CLI is the version of the CLI you run. Gateway is the version of the gateway package on your appliance, which is a separate number from the appliance release.

Exit status of appxen status

Upload a file or an entire directory to the knowledge base:

# Single file
appxen ingest ./report.pdf

# Entire directory (recursive by default)
appxen ingest ./docs/

# Only markdown files
appxen ingest ./docs/ --glob "*.md"

# Top-level files only
appxen ingest ./docs/ --no-recursive

# Upload and exit without waiting
appxen ingest ./docs/ --no-wait

# Wait up to 30 minutes for each file
appxen ingest ./scans/ --timeout 1800

# JSON output: waits, then prints the final state
appxen ingest ./docs/ --json
appxen ingest ./docs/ --json --no-wait   # the accepted state (status: queued)

The CLI uploads each file, then polls until ingestion completes (chunking, embedding, indexing). Progress bars show 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.

With --json, stdout is the array and nothing else; the progress goes to stderr. An entry is file, source_id, filename, status and chunk_count; a file that failed also has error with the reason. A file that is not ready when its --timeout passes counts as a failure, and so does one whose source disappears during the wait (someone deleted it). The command goes on waiting for the other files. Only a refused API key ends it at once, because no other file can succeed.

Supported file types

Unsupported file types are silently skipped when scanning a directory. The maximum file size is 100 MB. See Supported Formats for how each type is parsed.

Exit status of appxen ingest

A script tells a status 2 for failed files from a usage error by the output: with --json, failed files come with the document, each failed entry carrying error; a usage error prints nothing on stdout.

Semantic search over your knowledge base:

appxen search "refund policy for enterprise customers"
appxen search "error handling" --top-k 10
appxen search "deployment steps" --json

╭──────────── #1 refund-policy.md (score: 0.847) ──────────╮
│ Enterprise customers can request a refund within 30      │
│ days of the invoice date. Requests are sent to the       │
│ account team, who confirm the amount...                  │
╰──────────────────────── chunk: a1b2c3d4 ─────────────────╯
╭──────────── #2 support-handbook.md (score: 0.723) ───────╮
│ Refund requests that arrive through the support queue    │
│ are tagged "billing" and routed to the finance team...   │
╰──────────────────────── chunk: f6g7h8i9 ─────────────────╯

Create a workflow from a markdown file, run it with inputs, and save the output:

# Compile and save a workflow
appxen workflow create ./blog-post.md --name "Blog Post Pipeline"

# Run with inputs; starts it and waits for the end
appxen workflow run wf_abc123 \
  --input topic="AI in healthcare" \
  --save result.md

# Start it and return the execution id
appxen workflow run wf_abc123 -i topic=security --no-poll --json

# Wait for a running execution, up to 30 minutes
appxen workflow status exec_xyz789 --poll --timeout 1800

# Get the output, or one step's output
appxen workflow output exec_xyz789 --save result.md
appxen workflow output exec_xyz789 --step research

# Stop an execution
appxen workflow stop exec_xyz789

workflow run (unless --no-poll) and workflow status --poll wait until the execution ends: completed, failed, rejected, timed_out or aborted. An execution held at an approval gate (awaiting_approval) is approved or rejected in the console.

--save is refused with --no-poll (exit 2: there is no output to save yet), and with no output to write it is an error, never an empty file. With --json, stdout is one document, {"execution": ..., "steps": [...]}: the final state, or at the deadline the state as last seen; nothing after an interrupt. workflow stop on an execution that had already ended changes nothing, says so, and exits 0.

Exit status of appxen workflow run

Exit status of appxen workflow status