Xplain CLI

The Xplain CLI provides command-line access to all Xplain analytics operations. It mirrors the Python API namespaces so every operation available in code is also available from the terminal.

On this page

Installation
Overview
Session Management
Output Formats
Command Groups
- explore
- query
- select
- dimensions
- temporal
- models
- data
- config

Installation 

The CLI is included with the xplain Python package:

pip install xplain

Overview 

The CLI is organised into command groups that correspond to the XplainSession namespaces:

Group	Purpose
`explore`	Browse the object tree, inspect objects / dimensions / attributes
`query`	Execute queries, manage requests, retrieve results
`select`	Apply and manage selections (filters)
`dimensions`	Add / remove calculated dimensions and attributes (30+ types)
`temporal`	Relative time dimensions, sequences, longitudinal analysis
`models`	Predictive modeling, causal discovery
`data`	Object management, file import/export, sampling
`config`	Server settings, performance tuning, session management

The CLI also includes top-level session commands such as connect, startup, and init-xplain-session.

Every command supports --output json|csv|table to control the output format.

Session Management 

The CLI resolves a session in the following order:

Explicit ``–session`` option — pass a saved session name or a profile name from ~/.xplainpyrc.
In-process active session — set by a prior xplain connect call in the same process.
Last saved session — stored in ~/.xplainpy/sessions/.
Default profile from ``~/.xplainpyrc`` — if none of the above match, the CLI automatically connects using the default profile.

This means that if you have a ~/.xplainpyrc with a default profile (including a "startup" key), every command works out of the box — no explicit xplain connect is required.

Profile configuration 

Profiles are stored in ~/.xplainpyrc. Each profile can include a "startup" key that names the dataset to load automatically:

{
  "default": "xoedevtest",
  "profiles": {
    "xoedevtest": {
      "url": "https://xoedevtest.xplain-data.com",
      "user": "myuser@example.com",
      "password": "secret",
      "startup": "TestSet1"
    },
    "mimic": {
      "url": "https://xmimic.xplain-data.com",
      "user": "mimicuser@example.com",
      "password": "secret",
      "startup": "Mimic"
    }
  }
}

When the CLI auto-connects (or when you run xplain connect --profile …), the "startup" dataset is loaded so that explore, query, and other commands work immediately.

connect 

Explicitly connect to an Xplain server. Three connection modes are supported:

# 1. Profile — startup dataset from profile config
xplain connect --profile xoedevtest

# 2. Explicit credentials + dataset
xplain connect --url https://xoe.example.com --user admin --password secret \
    --startup TestSet1

# 3. Attach to an existing server session by ID
xplain connect --profile xoedevtest --session-id CED14155E7A90C9376749487A6B52C24
# or with an explicit URL:
xplain connect --url https://xoe.example.com --session-id CED14155E7A90C9376749487A6B52C24

# Use the default profile (no options needed)
xplain connect

# Connect and save the session for later reuse
xplain connect --profile xoedevtest --save-as mywork

Options:

--profile, -p: Profile name from ~/.xplainpyrc.
--url: Server URL (overrides profile).
--user, -u: Username (overrides profile).
--password: Password (overrides profile).
--session-id: Attach to an existing server session by its 32-character ID. Requires --url or --profile to supply the server URL. Since the dataset is already loaded on the server, --startup is not needed.
--startup, -s: Dataset / startup file to load (e.g. "TestSet1"). Overrides the profile’s "startup" key if both are given. Ignored when --session-id is used.
--save-as: Save the session under this name in ~/.xplainpy/sessions/ so it can be restored automatically in future CLI invocations.

startup 

Load an .xstartup configuration or a local .xview file into the active session:

# Load a saved startup configuration
xplain startup TestSet1.xstartup

# The .xstartup extension is optional
xplain startup TestSet1

# Load a local XView JSON file
xplain startup ./views/sales_view.xview

# Use a named profile/session and JSON output
xplain startup TestSet1.xstartup --session xoedevtest --output json

For .xstartup files, the CLI calls session.startup(file) and lets the server resolve the saved startup configuration. For .xview files, the CLI reads the local JSON file and calls session.startup_from_xview_config(...).

init-xplain-session 

Initialize the current Xplain server session via session.http_post("/init_xplain_session", {}):

xplain init-xplain-session
xplain init-xplain-session --session xoedevtest --output json

Output Formats 

All commands accept an --output flag:

--output json: Raw JSON (pipe-friendly, good for jq).
--output csv: Comma-separated values with a header row.
--output table: Formatted rich table for interactive use (default).

Command Groups 

explore 

Inspect the object hierarchy.

# Show the full object tree
xplain explore show-tree --output json

# Get metadata for an object
xplain explore get-object-info --object-name Patients --output json

# Get metadata for a dimension
xplain explore get-dimension-info \
    --object-name Patients --dimension-name Gender --output json

# Get metadata for an attribute
xplain explore get-attribute-info \
    --object-name Patients --dimension-name Gender \
    --attribute-name Gender --output json

# Navigate the tree at any level
xplain explore get-tree-details --output json
xplain explore get-tree-details --object-name Hospitalizations --output json

# Get the full structure (all objects, dimensions, attributes)
xplain explore get-full-object-structure --output json

# Search for states in a hierarchy
xplain explore get-tree-containing-string \
    --object Patients --dimension Gender --attribute Gender \
    --string "Male" --output json

query 

Execute analytical queries and manage requests.

Execute a one-shot request:

# COUNT Patients grouped by Gender
xplain query execute-request --output json --request '{
  "requestName": "gender_count",
  "aggregations": [
    {"aggregationType": "COUNT", "object": "Patients", "dimension": "Gender"}
  ],
  "groupBys": [{
    "subGroupings": [{
      "attribute": {
        "object": "Patients",
        "dimension": "Gender",
        "attribute": "Gender"
      }
    }]
  }],
  "selections": []
}'

Open a dynamic (live) request that recomputes on selection change:

xplain query open-request --delete-if-exists --output json --request '{
  "requestName": "live_gender",
  "aggregations": [
    {"aggregationType": "COUNT", "object": "Patients", "dimension": "Gender"}
  ],
  "groupBys": [{
    "subGroupings": [{
      "attribute": {
        "object": "Patients",
        "dimension": "Gender",
        "attribute": "Gender"
      }
    }]
  }],
  "selections": []
}'

Two-step workflow (create, then compute):

# Step 1: create without computing
xplain query create-request --delete-if-exists --output json --request '{
  "requestName": "step_query",
  "aggregations": [
    {"aggregationType": "SUM", "object": "Prescriptions", "dimension": "Costs (est.)"}
  ],
  "groupBys": [{
    "subGroupings": [{
      "attribute": {
        "object": "Prescriptions",
        "dimension": "Date",
        "attribute": "Date",
        "groupByLevel": "Years"
      }
    }]
  }],
  "selections": []
}'

# Step 2: compute
xplain query compute-request --request-name step_query --output json

Count an attribute (convenience):

xplain query count-attribute \
    --object-name Patients --dimension-name Gender \
    --attribute-name Gender --output json

Manage requests:

xplain query delete-request --request-name gender_count --output json
xplain query delete-all-requests --output json
xplain query pause-request --request-name live_gender --output json
xplain query unpause-request --request-name live_gender --output json

select 

Apply and manage selections (filters).

# Apply a selection
xplain select select --output json --selection '{
  "attribute": {
    "object": "Patients",
    "dimension": "Gender",
    "attribute": "Gender"
  },
  "selectedStates": ["Male"]
}'

# Select a numeric range
xplain select select-between \
    --object Patients --dimension "DoB" --attribute "Age" \
    --from- 20 --to 40 --output json

# View current selections
xplain select get-selections --output json

# Clear selections for an attribute
xplain select clear-selections --output json --selections '[{
  "attribute": {
    "object": "Patients",
    "dimension": "Gender",
    "attribute": "Gender"
  }
}]'

# Clear all selections
xplain select clear-all-selections --output json

# Undo / redo
xplain select go-back-in-selections --output json
xplain select go-forward-in-selections --output json

dimensions 

Add, remove, and manage calculated dimensions.

# Add an aggregation dimension
xplain dimensions add-aggregation-dimension --output json --request '{
  "baseDimension": {
    "object": "Patients",
    "dimension": "Gender"
  },
  "aggregationType": "COUNT",
  "name": "#Prescriptions"
}'

# Add a ratio dimension
xplain dimensions add-ratio-dimension --output json \
    --numerator '{"object": "Patients", "dimension": "Weight"}' \
    --denominator '{"object": "Patients", "dimension": "Height"}' \
    --name "BMI"

# Remove a dimension
xplain dimensions remove-dimension \
    --object-name Patients --dimension-name "#Prescriptions" --output json

# Remove only if it exists (no error if missing)
xplain dimensions remove-dimension-if-exists \
    --object-name Patients --dimension-name "#Prescriptions" --output json

temporal 

Temporal and longitudinal analysis.

# Add relative time dimensions
xplain temporal add-relative-time-dimensions --output json \
    --reference-time-dimension '{"object": "Diagnosis", "dimension": "Date"}' \
    --time-dimensions '[{"object": "Patients", "dimension": "DeathDate"}]' \
    --names '["TimeToEvent"]' \
    --relative-time-type TO_FIRST \
    --time-unit DAY

# Build a sorted sequence
xplain temporal build-sorted-sequence --output json \
    --dimensions-to-replicate '[{"object": "Lab", "dimension": "Date"}]' \
    --sort-criterion '{"object": "Lab", "dimension": "Date"}' \
    --names '["LabSequence"]' \
    --rank-dimension-name "LabRank"

# Run longitudinal analysis
xplain temporal run-longitudinal-analysis --output json \
    --config '{"analysisType": "SEQUENCE", ...}'

models 

Predictive modeling and causal discovery.

# List loaded models
xplain models get-model-names --output json

# Import a model file
xplain models import-model --file '{"fileName": "MyModel.xmodelresult"}' --output json

# Build a predictive model
xplain models build-predictive-model --output json --config '{
  "modelName": "GenderPredictor",
  "targetVariable": {"object": "Patients", "dimension": "Gender", "attribute": "Gender"},
  "modelType": "LOGISTIC_REGRESSION"
}'

# Get model variables
xplain models get-variable-list --model-name GenderPredictor --output json
xplain models get-variable-details --model-name GenderPredictor --output json

# Estimate causal graph
xplain models estimate-causal-graph --model-name GenderPredictor --output json

data 

Object management, import/export, sampling.

# List available analyses
xplain data list-analyses --output json

# Export results to Excel
xplain data export-results --output json --requests '[...]'

# Start / stop sampling
xplain data start-sampling --sample-fraction 0.1 --output json
xplain data stop-sampling --output json

config 

Server settings, performance, session management.

# Get session state
xplain config get-session --output json

# Refresh session from server
xplain config refresh --output json

# Load an analysis
xplain config load-analysis --analysis-name MyAnalysis --output json

# Performance tuning
xplain config set-max-threads --max-threads 4 --output json
xplain config enable-caching --output json

# Resource usage
xplain config resource-usage --output json