CLI Reference & Workflows

matrixai init <project_name> [--template <name>] [--output-dir <dir>] [--list-templates]

What it generates: a .mxai model file, a .mxtrain training contract, a sample CSV, and a quick-start instructions file.

matrixai init --list-templates
matrixai init my_email_classifier
matrixai init credit_risk --template classification
matrixai init fraud_detector --output-dir ~/projects/

matrixai prompt <description...> [-o <file>] [--semantic] [--json]

matrixai prompt "classify emails as spam, normal or urgent"
matrixai prompt "classify emails as spam, normal or urgent" -o email.mxai
matrixai prompt "assess fall risk for elderly patients" --semantic
cat description.txt | matrixai prompt - -o model.mxai
matrixai prompt "detect fraudulent transactions" --json

matrixai propose <description...> [--max-candidates <n>] [--provider <name>] [--json] [--include-compiled]

matrixai propose "classify legal documents" --max-candidates 3
matrixai propose "pharmacy dispensing system" --provider chat-completions-compatible
matrixai propose "churn predictor" --json --include-compiled

# Supervise an existing .semantic
matrixai supervise-prompt "my model" --proposal my_model.semantic

# Convert .semantic to .mxai directly
matrixai architect my_model.semantic -o my_model.mxai

# Validate structure (exit 0 = OK, exit 1 = error)
matrixai validate email_classifier.mxai

# Validate semantic plan before generating .mxai
matrixai validate-plan my_model.semantic

# Lint: errors + warnings + suggestions
matrixai lint email_classifier.mxai
matrixai lint email_classifier.mxai --strict   # fail on any warning (for CI)
matrixai lint email_classifier.mxai --json

# Format: apply canonical MatrixAI formatting
matrixai format email_classifier.mxai           # preview
matrixai format email_classifier.mxai --write  # format in place
matrixai format email_classifier.mxai --check  # CI check

# Type-check field and expression types
matrixai typecheck email_classifier.mxai

# Show internal representation (IR) as JSON
matrixai parse email_classifier.mxai

matrixai graph email_classifier.mxai                         # Mermaid (paste at mermaid.live)
matrixai graph email_classifier.mxai --format dot -o graph.dot  # Graphviz
matrixai graph email_classifier.mxai --format json

Runs the model with the same data on both the interpreter and the Python compiler and compares results. Detects numerical discrepancies between backends.

echo '{"subject": "Exclusive offer", "sender_score": 0.2, "body_length": 450}' > input.json
matrixai diagnose email_classifier.mxai --input input.json
matrixai diagnose email_classifier.mxai --input input.json --tolerance 1e-6 --json

# Optimization suggestions (read-only — never modifies the model)
matrixai optimize email_classifier.mxai

# Review sandbox permissions for actions
matrixai permissions email_classifier.mxai

# Translate if/then business rules to continuous mathematics
matrixai mathematize business_rules.txt
echo "if risk > 0.8 then alert" | matrixai mathematize -

# Expected output:
# if risk > 0.8 then alert
#   -> sigmoid(20 * (risk - 0.8))

matrixai compile email_classifier.mxai -o email_compiled.py
matrixai compile email_classifier.mxai --target differentiable-python -o email_diff.py

# scoring.mx:  utility(op) = quality(op) - 0.3 * cost(op) - 0.2 * latency(op)
matrixai eval scoring.mx --input '{"quality": 0.9, "cost": 0.4, "latency": 0.3}'
matrixai eval scoring.mx --input data.json --trace
matrixai eval scoring.mx --input data.json --call utility

# Portability report
matrixai backend-report email_classifier.mxai
matrixai backend-report email_classifier.mxai --target torch

# Run with differentiable backend
matrixai backend-run email_classifier.mxai --input input.json --parameters initial
matrixai backend-run email_classifier.mxai \
  --input input.json \
  --parameters runs/email_v1/params.best.json
matrixai backend-run email_classifier.mxai \
  --input input.json --target torch --device cuda \
  --parameters runs/email_v1/params.best.json

# Inspect expected parameters
matrixai backend-parameters email_classifier.mxai
matrixai backend-parameters email_classifier.mxai --validate runs/email_v1/params.best.json

# Validate a training contract
matrixai validate-training email.mxtrain

# Generate a training contract from a model + description
matrixai generate-training email_classifier.mxai \
  "classify emails as spam, normal or urgent" \
  -o email.mxtrain \
  --dataset-output email_template.csv

matrixai generate-training email_classifier.mxai "classify emails" \
  -o email.mxtrain --epochs 200 --learning-rate 0.01

matrixai generate-training credit_risk.mxai "classify credit applications" \
  -o credit.mxtrain --labels "approved,rejected,review" --target-name "decision"

# Generate model + contract in one step (starting from scratch)
matrixai generate-supervised \
  "classify emails as spam, normal or urgent" \
  -o models/email/ --stem email_classifier

# Generate synthetic data (200-50000 rows)
matrixai generate-dataset email_classifier.mxai \
  --training email.mxtrain --rows 500 --mode coherent -o data/

matrixai generate-dataset email_classifier.mxai \
  --training email.mxtrain --rows 1000 --seed 123 --mode coherent -o data/

Generated artefacts: params.best.json, params.final.json, metrics.json, training_trace.json, evaluation_report.json

matrixai train email_classifier.mxai --training email.mxtrain -o runs/email_v1/
matrixai train email_classifier.mxai --training email.mxtrain -o runs/email_v1/ --backend torch --device cuda

# Full pipeline in one command: description → trained model
matrixai train-supervised \
  "classify emails as spam, normal or urgent" \
  --train-data data/emails_train.csv \
  --eval-data data/emails_eval.csv \
  --epochs 150 \
  -o runs/email_v1/

# Evaluate a trained model
matrixai evaluate email_classifier.mxai \
  --params runs/email_v1/params.best.json \
  --training email.mxtrain \
  --data data/emails_test.csv \
  -o reports/eval_v1.json

# Without parameters (untrained — uses initial values)
matrixai run email_classifier.mxai \
  --input '{"subject": "URGENT", "sender_score": 0.95, "body_length": 120}'

# With trained parameters
matrixai run email_classifier.mxai --input input.json --params runs/email_v1/params.best.json --json

# Basic server on localhost
matrixai serve email_classifier.mxai \
  --params runs/email_v1/params.best.json \
  --api-key my_secret_key

# Exposed on network with read/write keys
matrixai serve email_classifier.mxai \
  --params runs/email_v1/params.best.json \
  --host 0.0.0.0 --port 8080 \
  --api-key WRITE_KEY --api-key-read READ_KEY

# Serve multiple models from a registry
matrixai serve --registry matrixai_registry/ --api-key my_secret_key

# With drift monitoring in production
matrixai serve email_classifier.mxai \
  --params runs/email_v1/params.best.json \
  --api-key my_secret_key \
  --continual-policy drift_policy.mxcontinual \
  --reference-accuracy 0.923

# Open Studio in the browser
matrixai playground --open
matrixai playground --port 9000 --open
matrixai playground --open

# Package for deployment (with optional Docker)
matrixai pack email_classifier.mxai \
  --params runs/email_v1/params.best.json \
  --outdir dist/email_v1/

matrixai pack email_classifier.mxai \
  --params runs/email_v1/params.best.json \
  --docker --outdir dist/email_v1/

cd dist/email_v1/ && docker compose up

# 1. Create project structure
matrixai init email_classifier && cd email_classifier/

# 2. Generate model + contract from description
matrixai generate-supervised \
  "classify incoming emails as spam, normal or urgent, using subject, sender score and body length" \
  -o . --stem email_classifier --epochs 200

# 3. Review the generated model
matrixai lint email_classifier.mxai
matrixai graph email_classifier.mxai --format mermaid

# 4. Generate synthetic test data
matrixai generate-dataset email_classifier.mxai \
  --training email_classifier.mxtrain --rows 1000 --mode coherent -o data/

# 5. Train
matrixai train email_classifier.mxai --training email_classifier.mxtrain -o runs/v1/

# 6. Check results
cat runs/v1/evaluation_report.json

# 7. Manual test
matrixai run email_classifier.mxai \
  --params runs/v1/params.best.json \
  --input '{"subject": "Exclusive offer", "sender_score": 0.1, "body_length": 800}'

# 8. Register the version
matrixai registry push runs/v1/ --name email-classifier --version v1.0
matrixai registry tag email-classifier@v1.0 prod

# 9. Serve as API
matrixai serve email_classifier.mxai \
  --params runs/v1/params.best.json \
  --api-key $MATRIXAI_API_KEY --port 8000

matrixai validate email_classifier.mxai         # structural errors
matrixai lint email_classifier.mxai             # errors + warnings
matrixai graph email_classifier.mxai            # visualise the computation graph
matrixai backend-report email_classifier.mxai   # backend compatibility
matrixai diagnose email_classifier.mxai --input test_input.json  # runtime vs compiled
matrixai optimize email_classifier.mxai         # optimisation suggestions
matrixai typecheck email_classifier.mxai        # type consistency
matrixai parse email_classifier.mxai            # internal representation

matrixai continual status drift_policy.mxcontinual
matrixai continual audit drift_policy.mxcontinual \
  --drift-report reports/drift_week.json \
  --prompt "classify emails as spam, normal or urgent"

matrixai refine "classify emails as spam, normal or urgent" \
  --evaluation runs/v1/evaluation_report.json \
  --mxai email_classifier.mxai --hint "improve urgent recall" \
  --accept --mxai-output email_v2.mxai --chain-output chain_v2.json --iteration 2

matrixai train email_v2.mxai --training email_classifier.mxtrain -o runs/v2/
matrixai evaluate email_v2.mxai --params runs/v2/params.best.json \
  --training email_classifier.mxtrain -o reports/eval_v2.json

matrixai registry push runs/v2/ --name email-classifier --version v2.0

matrixai continual promote drift_policy.mxcontinual \
  --approval-report reports/approval_v2.json \
  --candidate-params runs/v2/params.best.json \
  --human-approved --approved-by "name@company.com"

# Emergency rollback if needed:
matrixai continual rollback drift_policy.mxcontinual --dry-run
matrixai continual rollback drift_policy.mxcontinual

# Option 1: ONNX for external runtime
matrixai export-onnx email_classifier.mxai --params runs/v1/params.best.json \
  -o exports/email_v1.onnx --validate --manifest exports/email_v1_manifest.json

# Option 2: Full edge bundle
matrixai export-bundle email_classifier.mxai --params runs/v1/params.best.json \
  --outdir exports/edge_bundle/

# Option 3: Browser bundle (WebAssembly)
matrixai export-wasm email_classifier.mxai --params runs/v1/params.best.json \
  --outdir exports/wasm_bundle/

# Option 4: Docker image ready to deploy
matrixai pack email_classifier.mxai --params runs/v1/params.best.json \
  --docker --outdir dist/email_v1/
cd dist/email_v1/ && docker compose up