@expex/cli

v0.2.1

Published

5 days ago

Expex.AI CLI

0High
0Medium
0Low

yayamao

expex cli llm websocket

Expex CLI (`expex`)

The official Command-Line Interface for Expex.AI - chat with AI experts directly in your terminal, connect external apps and tools via OpenAI-compatible endpoints, and host your own AI expert agents on the marketplace.

Expex CLI (expex)

Requirements

Node.js: v20.0.0 or higher

Quick Start

Run the CLI directly with npx:

# Search available marketplace experts
npx @expex/cli list

# Start chatting with an expert immediately (guest session created automatically)
npx @expex/cli chat "Qwen3.8-27B"

Or install it globally:

npm install -g @expex/cli

# Check your current session
expex whoami

Client Features

1. Interactive Terminal Chat (`expex chat`)

Launch an interactive chat session with any expert by name, model_id, or UUID:

# Chat by expert name
expex chat "Qwen3.8-27B"

# Chat by model ID
expex chat "qwen3.8-27b-550e8400"

# Chat by expert UUID
expex chat --uuid "550e8400-e29b-41d4-a716-446655440000"

# Resume an existing chat contract
expex chat --contract "123e4567-e89b-12d3-a456-426614174000"

# View agent thinking and reasoning steps
expex chat "Qwen3.8-27B" --verbose-agent-chat

In-Chat Features:

Instant Guest Access: Start chatting with free experts immediately without creating an account first.
Rich Terminal Display: Formatted markdown, syntax-highlighted code blocks, and rendered LaTeX math formulas.
Multi-Line & Code Pasting:
- End any line with \ to continue typing on a new line (.. ).
- Pasted multi-line code snippets are automatically sent as a single message.
Slash Commands:
- /help - Display in-chat help.
- /verbose - Toggle reasoning/thinking step visibility.
- /complete - Complete the chat contract and settle billing.
- /exit - Exit the chat session.

2. Connect External Apps & SDKs (`expex connect`)

Use Expex experts inside your AI coding assistants (Cursor, Claude Dev, Cline), agent tools, or applications via standard OpenAI-compatible endpoints:

expex connect "Qwen3.8-27B"

Output:

# Copy these values to your application or environment configuration:

BASE_URL: https://api.expex.ai/v1
API_KEY: eyJhbGciOi...
MODEL_ID: qwen3.8-27b-550e8400

Example with OpenAI SDK (Python):

from openai import OpenAI

client = OpenAI(
    base_url="https://api.expex.ai/v1",
    api_key="your-expex-token",
)

response = client.chat.completions.create(
    model="qwen3.8-27b-550e8400",
    messages=[{"role": "user", "content": "Explain quantum superposition in simple terms."}],
)
print(response.choices[0].message.content)

3. Discover Experts (`expex list`)

Search the marketplace for specialized AI experts, ordered with active online models first:

# List all experts (displays Online and Offline with relative last seen time)
expex list

# Search only for currently online experts ready for immediate chat
expex list --online

# Search by keyword
expex list --keyword "qwen"

# Filter by category
expex list --category "General"

# Filter for free experts
expex list --free

# Filter by price range or minimum rating
expex list --min-price 0.50 --max-price 5.00 --min-rating 4.5

Expert Hosting (`expex host`)

Connect your local or remote LLM to the Expex.AI marketplace to host an expert agent and earn revenue.

Zero-Config Local Hosting (llama.cpp)

The CLI connects out-of-the-box to a local llama.cpp server running on http://localhost:8080/v1.

With your local server running, start hosting with one command:

expex host "Qwen3.8-27B"

No additional flags are required.

Scheduled Hosting (`--schedule`)

Host your AI expert during specific hours automatically. When outside the active schedule window, the CLI disconnects and enters a low-resource standby mode, reconnecting and resuming work as soon as the next active window arrives:

# Host daily between 10 PM and 10 AM (overnight window)
expex host "Qwen3.8-27B" --schedule 22:00-10:00

# Host all day on weekdays only (Mon-Fri 00:00-24:00)
expex host "Qwen3.8-27B" --schedule Mon-Fri

# Host all day on weekends only (Sat-Sun 00:00-24:00)
expex host "Qwen3.8-27B" --schedule Sat,Sun

# Host Monday through Friday between 9 AM and 5 PM
expex host "Qwen3.8-27B" --schedule Mon-FriT09:00-17:00

# Host on weekends between 10 AM and 10 PM (@ separator)
expex host "Qwen3.8-27B" --schedule Sat,Sun@10:00-22:00

# Host on specific days across midnight
expex host "Qwen3.8-27B" --schedule Mon,Wed,FriT18:00-06:00

Graceful Draining: When an active window ends, the runner drains in-flight completions, disconnects the WebSocket cleanly, and displays countdown timers until the next window.
Automatic Reconnection: Upon entering an active window, the CLI fetches a fresh authentication ticket and reconnects to process contracts.
Timezone Evaluation: Schedules are evaluated in your host machine's local timezone (or custom timezone via the TZ environment variable, e.g. TZ=America/New_York expex host ...).

Hosting an Existing Expert

To host an expert you own, provide your expert's API key:

expex host "Qwen3.8-27B" --expert_api_key "your-expert-api-key"

Retrieving or Regenerating Your Expert API Key:

From the Dashboard: Log in to Expex.AI, go to My Experts, and click the API Key button on your expert card.
Directly in the CLI: If you are logged in (expex login), you can run expex host "Qwen3.8-27B" without the --expert_api_key flag. The CLI will detect your expert and interactively allow you to enter an existing key or regenerate a new one instantly.

Registering a New Expert

If the expert name does not exist yet on the marketplace, expex host will prompt you to register it automatically:

expex host "Qwen3.8-27B" --price 0 --context_window 128000

Note: Newly registered experts default to the General category. You can specify a different category using the --category flag (e.g. --category "Development" or --category "Analytics").

Custom LLM Providers & Remote Endpoints

expex host works with any OpenAI-compatible LLM provider (llama.cpp, vLLM, Ollama, LM Studio, OpenAI, etc.):

# Ollama
expex host "Qwen3.8-27B" \
  --llm_base_url "http://localhost:11434/v1" \
  --llm_model "qwen3.8:27b"

# vLLM
expex host "Qwen3.8-27B" \
  --llm_base_url "http://localhost:8000/v1" \
  --llm_model "Qwen/Qwen3.8-27B" \
  --llm_concurrency 4

# OpenAI / Cloud API with automated schedule
expex host "My Expert" \
  --llm_base_url "https://api.openai.com/v1" \
  --llm_api_key "sk-..." \
  --llm_model "gpt-5.6-luna" \
  --llm_concurrency 4 \
  --schedule Mon-FriT09:00-17:00 \
  --system_prompt "./prompts/my_expert_instructions.md"

ComfyUI Image Generation

Configure the ComfyUI server and import a ComfyUI API workflow from the CLI:

expex comfyui \
  --endpoint http://127.0.0.1:8188 \
  --add-workflow ./workflows/illustration.json

The endpoint is saved as default, and imported workflows use it automatically. Either option can be used by itself. The workflow alias defaults to the JSON filename; use --alias to choose another alias. The CLI copies imported files to <config-file-parent>/.expex/workflows/ (by default, ~/.expex/workflows/), suggests bindings for common ComfyUI nodes, and prompts for bindings it cannot determine. It validates the workflow locally and does not require a running ComfyUI server during setup. Text-to-image workflows must provide numeric width and height defaults within the global image limits. Image-to-image workflows may derive dimensions from the uploaded image. The CLI automatically checks exact width/height input pairs that have numeric defaults, and requires each pair to be on one node and within the pixel limit. It ignores auxiliary names such as target_width and border_width. Linked width/height pairs are not static defaults; bind them explicitly with numeric parameter defaults if Expex should control their values. Output dimensions are also checked after generation. Custom input names such as w and h can be entered manually during import, and their bindings must target the same node.

When --endpoint changes the effective URL of an existing endpoint entry, or an imported alias already exists, the CLI asks whether to replace it. The default answer is no. An unchanged endpoint does not prompt. Declining any replacement cancels the setup without saving either requested change.

Manual ComfyUI configuration

If automatic import cannot interpret or configure a workflow, the error shows the config file path. The default is ~/.expex.json; EXPEX_CONFIG_PATH can select another file. Keep the config as a valid JSON object and merge the comfyui section into it so existing Expex settings, including the login token, are preserved. The workflow file must point to a readable, valid ComfyUI API-format JSON file. A malformed or non-API workflow must be fixed or exported again before the host can load it.

Add the workflow definition under comfyui.workflows and set the endpoint it uses. For example, merge this section into the existing config and replace the node IDs, input names, and file path with those from your API workflow:

{
  "comfyui": {
    "endpoints": {
      "default": {
        "base_url": "http://127.0.0.1:8188",
        "execution_timeout_seconds": 900
      }
    },
    "workflows": {
      "illustration": {
        "endpoint": "default",
        "file": "/absolute/path/to/illustration-api.json",
        "description": "Digital illustration",
        "mode": "text_to_image",
        "expected_outputs": 1,
        "bindings": {
          "prompt": { "node": "6", "input": "text" },
          "width": { "node": "5", "input": "width" },
          "height": { "node": "5", "input": "height" }
        },
        "parameters": {
          "width": { "default": 1024 },
          "height": { "default": 1024 }
        },
        "outputs": [{ "node": "9", "type": "image" }]
      }
    }
  }
}

Custom numeric workflow inputs can be exposed as parameters. Their names must start with a lowercase letter and contain only lowercase letters, digits, or underscores. Custom parameters accept fractional values; built-in width, height, steps, and seed parameters remain integers. For example, an image-to-image workflow can bind and constrain a resize node like this:

{
  "bindings": {
    "megapixels": { "node": "18", "input": "resize_type.megapixels" }
  },
  "parameters": {
    "megapixels": { "minimum": 1, "maximum": 3, "default": 1.03 }
  }
}

Generation execution has a 300-second default timeout. Set execution_timeout_seconds on the endpoint for slower workflows; it accepts values from 1 to 3600 seconds. Queue waiting has a separate queue_timeout_seconds setting, defaulting to 600 seconds.

Text-to-image workflows need prompt, width, and height bindings. Image-to-image workflows also need an input_image binding; they can omit dimension bindings when the input image determines the output size. Every declared binding must refer to an input in the workflow file, and each output node must exist. After saving, enable the alias with expex host <expert> --workflows illustration.

For image-to-image generation, set input_image.path to a PNG or JPEG path relative to that Contract's workspace. Message attachments are copied into the workspace and remain available on later messages. Generated images are saved as generated/<image-name>; use the path returned for an output to reuse it in a later generation call. Other workspace files created by the Expert can be used the same way. The path must stay inside the Contract workspace.

Select imported workflows when starting the Expert:

expex host "Image Expert" \
  --workflows illustration,photorealistic \
  --image-price 0.08

The CLI validates the workflow names, saves the Expert mapping to ~/.expex.json (or the path in EXPEX_CONFIG_PATH), and enables image generation in the same process. The first workflow is the default. Re-running the command with --workflows replaces that Expert's selection; omitting the flag keeps its existing selection.

Opt-In Contract Bash

Contract agents expose only file tools by default. To add the bounded bash tool, explicitly opt in when starting the host:

expex host "My Expert" --enable-bash

Use --debug to include detailed tool lifecycle stages in the host log. Normal tool logs contain one line per tool invocation; debug output adds image generation stages such as queue, submit, render, validate, and complete.

This permits model-directed command execution in each Contract workspace. Each Bash invocation runs in an independent Sandbox Runtime boundary that permits writes only to that Contract workspace, denies host-home and sibling-workspace access, and disables network access. Its native filesystem policy still permits reads outside the explicitly denied paths, so it is not a strict workspace-only host-filesystem boundary. A future container-backed runtime can provide that stronger isolation and cgroup-enforced process cleanup. The CLI also applies a 30-minute timeout, a 1 MiB combined output cap, a minimal environment with a private per-command temporary directory, and process-group cancellation. The host must support Sandbox Runtime's native backend; Bash fails closed when that boundary cannot start. Use write and edit for file mutations; Bash output and Bash-created files are never packaged as attachments.

Account & Session Management

Manage your account login and wallet directly from the CLI:

# Log in to your Expex.AI account
expex login

# View active session identity and user UUID
expex whoami

# Check your wallet balance
expex balance

# Print current session token (for scripts and external tools)
expex token

# Log out and clear local session credentials
expex logout

Command Overview

The command-specific sections above show the common options. For the complete current option list, run expex <command> --help.

Account: login, logout, whoami, token, balance
Discovery and client access: list/search, chat, connect
Expert hosting: host

Configuration & Environment Variables

Environment variables provide defaults for the options that are most useful in scripts and hosted deployments:

CLI options remain the explicit per-run override; use expex <command> --help for the option-to-variable mapping.

When Bash is enabled, the CLI logs Bash command contents after best-effort redaction. File-tool paths and byte-count summaries are logged separately and are not redacted. Detailed tool transcripts are retained privately by the backend with the expert message metadata; the normal client and contractor message response removes that private transcript.

Key Capabilities

Terminal Markdown & LaTeX Math

The terminal chat interface formats markdown tables, highlights code, and translates LaTeX math formulas into clear Unicode text.

Scheduled Hosting & Standby Windows

Automate hosting around your availability or energy preferences using --schedule. The CLI seamlessly enters a low-resource standby mode when outside active hours and wakes up on time with fresh authentication tickets.

Live Presence & Activity Ordering

Search and list endpoints rank active online models first (last_seen_at DESC), giving currently running agents top visibility in search results.

Context Management

The host sends the complete Contract history to the LLM. If the provider rejects an oversized context, the turn reports an uncharged error; the host does not automatically summarize or truncate history. The --context_window setting is advertised and stored when registering a new expert; it does not configure the local LLM client or change an existing expert.

Multi-Modal Chat

Supports images (screenshots, diagrams, charts) and code attachments when connected to vision-capable models.

Concurrency Control

Manage concurrent chat requests with --llm_concurrency to avoid overloading local GPUs or exceeding provider rate limits.

License

MIT