CLI Reference

Complete command reference for the xiantong CLI client

CLI Reference

The xiantong-cli is a terminal client that connects to a running xiantong headless server over WebSocket. It provides commands for listing resources, managing sessions, sending messages with real-time streaming, and validating server health.

Installation#

Ensure xiantong-cli is included in your xiantong installation or provided by your deployment package, then confirm it is on PATH.

xiantong-cli --help
xiantong-cli <command>

If you need to run a development CLI directly, follow the instructions for your current xiantong distribution or internal repository.

Quick Start#

The fastest way to try it out — no server setup needed:

# Self-contained run (spawns a server automatically)
ANTHROPIC_API_KEY=sk-... xiantong-cli run "Hello, world!"

Connection Options#

Flags override environment variables. If --workspace is omitted, the first available workspace is used automatically.

Commands#

Info & Health#

Resource Listing#

Session Operations#

Send Message (Streaming)#

xiantong-cli send <session-id> <message>
echo "Summarize this" | xiantong-cli send <session-id>

The send command subscribes to session:event and streams the AI response to stdout in real time:

Raw RPC#

xiantong-cli invoke <channel> [json-args...]   # Send any RPC channel
xiantong-cli listen <channel>                   # Subscribe to push events

invoke sends a request to any channel and prints the response. listen subscribes to a push channel and prints events as they arrive (Ctrl+C to stop).

Run (Self-Contained)#

xiantong-cli run <prompt>
xiantong-cli run --workspace-dir ./project --source github "List open PRs"

The run command is fully self-contained — it spawns a headless server, creates a session, sends the prompt, streams the response, and exits. No separate server setup needed. An API key is resolved from --api-key, $LLM_API_KEY, or a provider-specific env var (e.g., $ANTHROPIC_API_KEY, $OPENAI_API_KEY).

LLM Configuration:

# Multi-provider examples
xiantong-cli run --provider openai --model gpt-4o "Summarize this repo"
GOOGLE_API_KEY=... xiantong-cli run --provider google --model gemini-2.0-flash "Hello"
xiantong-cli run --provider anthropic --base-url https://openrouter.ai/api/v1 --api-key $OR_KEY "Hello"

Validate Server#

# Against a running server
xiantong-cli --validate-server --url ws://127.0.0.1:9100 --token <token>

# Self-contained (auto-spawns a server)
xiantong-cli --validate-server

When no --url is provided, --validate-server automatically spawns a local headless server, runs the validation, and shuts it down. Runs a 21-step integration test covering the full server lifecycle including source and skill creation:

1. Connect + handshake
2. credentials:healthCheck
3. system:versions
4. system:homeDir
5. workspaces:get
6. sessions:get
7. LLM_Connection:list
8. sources:get
9. sessions:create (temporary __cli-validate-* session)
10. sessions:getMessages
11. Send message + stream (text response)
12. Send message + tool use (Bash tool)
13. sources:create (temporary Cat Facts API source)
14. Send + source mention (uses the created source)
15. Send + skill create (writes SKILL.md via Bash)
16. skills:get (verify skill appears)
17. Send + skill mention (invokes the created skill)
18. skills:delete (cleanup)
19. sources:delete (cleanup)
20. sessions:delete (cleanup)
21. Disconnect

Note: This test mutates workspace state — it creates and deletes a temporary session, source, and skill. All resources are cleaned up on completion. Continues on failure and reports a summary. Use --json for machine-readable output:

xiantong-cli --validate-server --json | jq '.results[] | select(.status == "FAIL")'

Troubleshooting#