Skip to main content

SynapseX CLI

The official command-line interface for interacting with SynapseX services directly from your terminal.

Installation​

pip install synapsex-cli

Or with pipx (recommended for CLI tools):

pipx install synapsex-cli

Configuration​

Interactive Setup​

synapsex configure

This prompts for:

  • API Key
  • License Key (optional)
  • Default model
  • Output format preference

Manual Configuration​

# Set API key
synapsex configure --api-key sk-synapsex-your-key

# Set license key
synapsex configure --license-key SQXL-XXXX-XXXX-XXXX

# Check configuration
synapsex configure --show

Environment Variables​

export SYNAPSEX_API_KEY="sk-synapsex-your-key"
export SYNAPSEX_LICENSE_KEY="SQXL-XXXX-XXXX-XXXX"
export SYNAPSEX_MODEL="synapsex-14b"

Commands Overview​

CommandDescription
synapsex chatChat with AI models
synapsex trainManage training jobs
synapsex datasetManage datasets
synapsex modelsList available models
synapsex licenseLicense management
synapsex feedbackSubmit feedback
synapsex configureConfigure credentials
synapsex versionShow version info

Chat Commands​

Basic Chat​

# Simple question
synapsex chat "What is machine learning?"

# Multi-line prompt
synapsex chat "Explain this code:
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)"

Chat Options​

synapsex chat "Your prompt" [OPTIONS]
OptionShortDescriptionDefault
--model-mModel to usesynapsex-v1
--temperature-tCreativity (0.0-2.0)0.7
--max-tokensMax response length2048
--system-sSystem promptNone
--rerank-rReranking modenone
--no-streamDisable streamingStreaming on
--json-jJSON outputRich format

Examples​

# Use specific model
synapsex chat "Hello" --model synapsex-14b

# Creative writing
synapsex chat "Write a poem about AI" --temperature 1.2

# With system prompt
synapsex chat "Translate to Portuguese" \
  --system "You are a professional translator."

# Quantum reranking for complex queries
synapsex chat "Analyze market trends" --rerank quantum_gpu

# JSON output for scripting
synapsex chat "Hello" --json | jq '.content'

Reranking Modes​

ModeDescriptionSpeedQuality
noneNo reranking⚡⚡⚡★★★
cpuCPU reranking⚡⚡★★★★
quantum_gpuQuantum GPU⚡★★★★★

Interactive Mode​

# Start interactive chat session
synapsex chat --interactive

# With specific model
synapsex chat --interactive --model synapsex-14b

In interactive mode:

  • Type messages and press Enter
  • Use /clear to reset conversation
  • Use /model <name> to switch models
  • Use /exit or Ctrl+C to quit

Training Commands​

Start Training​

synapsex train start [OPTIONS]
OptionShortDescriptionRequired
--type-tType: sft, dpo, loraYes
--model-mBase modelNo
--dataset-dDataset IDNo
--gpus-gNumber of GPUsNo
--epochs-eTraining epochsNo
--batch-sizeBatch sizeNo
--learning-rateLearning rateNo

Training Examples​

# SFT training
synapsex train start --type sft --model synapsex-14b

# LoRA with 4 GPUs
synapsex train start --type lora --gpus 4 --epochs 5

# DPO with custom dataset
synapsex train start --type dpo --dataset my-preferences

Monitor Training​

# Job status
synapsex train status <job-id>

# Watch progress (real-time)
synapsex train status <job-id> --watch

# List all jobs
synapsex train list

# Filter by status
synapsex train list --status running
synapsex train list --status completed
synapsex train list --status failed

Training Logs​

# View logs
synapsex train logs <job-id>

# Follow logs in real-time
synapsex train logs <job-id> --follow

# Last 100 lines
synapsex train logs <job-id> --tail 100

Cancel Training​

synapsex train cancel <job-id>

Dataset Commands​

Upload Dataset​

# Upload JSONL file
synapsex dataset upload ./data.jsonl --name "my-dataset"

# With description
synapsex dataset upload ./data.jsonl \
  --name "support-v2" \
  --description "Customer support conversations"

List Datasets​

synapsex dataset list

# Detailed view
synapsex dataset list --verbose

Dataset Info​

synapsex dataset info <dataset-id>

Delete Dataset​

synapsex dataset delete <dataset-id>

# Force delete (no confirmation)
synapsex dataset delete <dataset-id> --force

Download Dataset​

synapsex dataset download <dataset-id> --output ./download.jsonl

Models Commands​

List Models​

synapsex models list

# Show all details
synapsex models list --verbose

Model Info​

synapsex models info synapsex-14b

Output:

Model: synapsex-14b
Parameters: 14B
Context Length: 32768 tokens
Capabilities: chat, code, analysis
Pricing: $0.0005/1K tokens

License Commands​

Check License​

synapsex license info

Output:

Plan: Professional
Status: Active
Expires: 2026-12-31
Features:
  ✓ Quantum Reranking
  ✓ Custom Training
  ✓ Priority Support
Quota:
  API Calls: 45,000/100,000 (45%)
  Training Hours: 12/50 (24%)

Validate License​

synapsex license validate

Activate License​

synapsex license activate SQXL-XXXX-XXXX-XXXX

Feedback Commands​

Submit Feedback​

# Quick rating
synapsex feedback submit --request-id req-123 --rating 5

# With comment
synapsex feedback submit \
  --request-id req-123 \
  --rating 4 \
  --comment "Good but could be more concise"

List Feedback​

synapsex feedback list --limit 10

Global Options​

These options work with all commands:

OptionDescription
--helpShow help for command
--versionShow CLI version
--verboseVerbose output
--quietMinimal output
--jsonJSON output format
--no-colorDisable colored output

Output Formats​

Default (Rich)​

synapsex chat "Hello"
╭─ SynapseX Response ─────────────────────────────╮
│ Hello! How can I assist you today?             │
│                                                 │
│ Model: synapsex-v1  Tokens: 23                 │
╰─────────────────────────────────────────────────╯

JSON​

synapsex chat "Hello" --json
{
  "content": "Hello! How can I assist you today?",
  "model": "synapsex-v1",
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 15,
    "total_tokens": 23
  }
}

Plain​

synapsex chat "Hello" --plain
Hello! How can I assist you today?

Scripting Examples​

Batch Processing​

#!/bin/bash
# Process multiple files

for file in ./prompts/*.txt; do
    prompt=$(cat "$file")
    output="${file%.txt}.response.txt"
    synapsex chat "$prompt" --plain > "$output"
    echo "Processed: $file"
done

Pipeline Integration​

# Use with pipes
echo "Summarize this article" | synapsex chat --stdin

# Chain commands
cat document.txt | synapsex chat "Translate to Spanish:" --stdin --plain > spanish.txt

JSON Processing​

# Extract specific fields
synapsex chat "List 5 programming languages" --json | \
  jq -r '.content' | \
  grep -E "^[0-9]+\."

Monitoring Script​

#!/bin/bash
# Watch training job

JOB_ID="$1"
while true; do
    status=$(synapsex train status "$JOB_ID" --json | jq -r '.status')
    progress=$(synapsex train status "$JOB_ID" --json | jq -r '.progress')
    
    echo "[$status] Progress: $progress%"
    
    if [[ "$status" == "completed" ]] || [[ "$status" == "failed" ]]; then
        break
    fi
    
    sleep 60
done

Troubleshooting​

Common Issues​

Authentication Failed

# Check configuration
synapsex configure --show

# Reset and reconfigure
synapsex configure --reset
synapsex configure

Connection Timeout

# Increase timeout
synapsex chat "Hello" --timeout 60

Rate Limited

# Check current usage
synapsex license info

# Wait and retry (automatic with --retry)
synapsex chat "Hello" --retry 3

Debug Mode​

# Enable debug output
synapsex chat "Hello" --debug

# Very verbose
synapsex chat "Hello" -vvv

Log Location​

# View CLI logs
cat ~/.synapsex/cli.log

# Tail logs
tail -f ~/.synapsex/cli.log

Configuration File​

Location: ~/.synapsex/config.yaml

api_key: sk-synapsex-your-key
license_key: SQXL-XXXX-XXXX-XXXX
defaults:
  model: synapsex-14b
  temperature: 0.7
  max_tokens: 2048
  rerank_mode: none
output:
  format: rich  # rich, json, plain
  color: true
  stream: true
api:
  base_url: https://api.synapsex.ai
  timeout: 30
  retries: 3

See Also​