Datex Studio CLI (dxs)

Command-line interface for Datex Studio low-code platform, designed for LLM-based AI agents.

Key Features

• Structured Output: YAML (default), JSON, and CSV formats for programmatic consumption
• Response Envelopes: All responses include metadata (timestamp, CLI version, counts)
• Concise Mode: Default behavior strips null values to reduce token usage
• Multi-Identity Auth: Support multiple organizational accounts with seamless switching
• Restricted Mode: Safe operation mode that blocks destructive commands
• Actionable Errors: Error responses include suggestion lists for resolution

Installation

# Using uv (recommended)
uv pip install datex-studio-cli

# Using pip
pip install datex-studio-cli

Quick Start

# Authenticate with Azure Entra (opens your browser; device code when headless)
dxs auth login

# Check authentication status
dxs auth status

# List repositories in your organization
dxs source repo list

# View commit history for a repository
dxs source log --repo 10 --limit 20

# View branch details
dxs source branch show 12345

# Explore application structure
dxs source explore info --branch 12345

Output Format

Response Envelopes

All commands return structured responses with metadata:

# Single item response
branch:
  id: 12345
  name: main
  status: ACTIVE
metadata:
  timestamp: '2024-01-15T10:30:00Z'
  cli_version: 0.5.0
  success: true

# List response
branches:
  - id: 12345
    name: main
  - id: 12346
    name: feature-x
metadata:
  timestamp: '2024-01-15T10:30:00Z'
  cli_version: 0.5.0
  count: 2
  success: true

Concise vs Full Mode

By default, concise mode strips null values and verbose metadata:

# Default (concise) - smaller output
dxs source branch show 12345

# Full output - includes all fields
dxs source branch show 12345 --full

Error Responses

Errors include actionable suggestions:

error:
  code: DXS-AUTH-002
  message: Not authenticated
  suggestions:
    - Run 'dxs auth login' to authenticate
    - Check if your token has expired with 'dxs auth status'
metadata:
  success: false
  timestamp: '2024-01-15T10:30:00Z'

Configuration

Priority Chain

Configuration values are resolved in order:

1. CLI flags (--repo 10)
2. Environment variables (DXS_REPO=10)
3. Config file (~/.datex/config.yaml)
4. Defaults

Environment Variables

Config File

# View current configuration
dxs settings list

# Set a default
dxs settings set default_repo 10

# Get a specific value
dxs settings get default_repo

Configuration stored in ~/.datex/config.yaml. Credentials stored separately in ~/.datex/credentials.yaml.

Restricted Mode

Set DXS_RESTRICTED_MODE=1 to block potentially dangerous operations:

• File-modifying operations (--save)
• Destructive actions (delete, logout --all, publish, deploy)
• CRM attachment downloads

Commands

Authentication (dxs auth)

One selector grammar is shared by login, switch, and init: an email address derives the tenant from its domain (works on a fresh machine), a domain or tenant GUID names the tenant directly, anything else is an organization name. --domain/--tenant-id name the tenant to authenticate against and always win; combined with an email selector they express a guest signing in to another organization's tenant. A usable cached identity for the target skips the browser entirely (--force re-authenticates).

Multi-Identity Workflow:

# Login to primary organization
dxs auth login

# Customer self-service: the tenant is derived from your address
dxs auth login you@csw-wi.com

# Login to an additional organization (fresh auth against its tenant)
dxs auth login OtherOrg

# List all identities
dxs auth list

# Switch between identities — org name, domain, tenant ID, or username
dxs auth switch OtherOrg
dxs auth switch csw-wi.com

CLI Settings (dxs settings)

Source Control (dxs source)

Direct commands on the source group:

Common Source Control Examples:

# View recent commits
dxs source log --repo 10 --limit 20

# View pending changes
dxs source diff --branch 100

# View configuration history with diffs
dxs source history userGrid --branch 100 --diff

# Check who has locks
dxs source locks --repo 10

# Compare two branches
dxs source compare --source 100 --target 200

Branch Management (dxs source branch)

Branch Listing Options:

# List all branches in a repo
dxs source branch list --repo 10

# Filter by status
dxs source branch list --repo 10 --status feature

# Show branches with pending changes
dxs source branch list --repo 10 --with-changes

# Sort by modification date
dxs source branch list --repo 10 --sort modified --desc

Package References (dxs source reference)

# Pin Module1 to a newly published version on feature branch 3101
dxs source reference set -b 3101 -p Module1 -v 20260714.1000

Rebuilds the branch's flattened reference list after the bump and refuses the write if the result would contain a version conflict (the same package pinned at two versions) or a circular reference.

Package Cascade (dxs source cascade)

When a package is republished, every package that references it stays pinned to the old version until it is re-pinned and republished itself. The cascade automates that fan-out.

# 1. Plan the cascade from a package you just published
dxs source cascade plan -p Module1 -v 20260714.1000 -O json > plan.json

# 2. Review what it would do — mutates nothing
dxs source cascade run --plan plan.json --dry-run

# 3. Execute
dxs source cascade run --plan plan.json

plan walks reverse-references from the origin package and emits update nodes grouped into topological levels, plus a staleApplications list — applications that consume an affected package but cannot be cascaded automatically.

• --org scopes traversal to a single organization. Omit it and the cascade spans consumers across all organizations, which is rarely what you want.
• --max-depth limits how far the traversal follows the reference chain.

run executes each level bottom-up, feeding each package's newly published version forward to its dependents.

Before mutating anything it applies the same guardrails as branch publish: each node's Main branch is resolved to its owning organization and checked against the current identity (once per distinct organization), then the run is confirmed. Each re-pinned feature branch is validated before it is committed, so a broken reference set never reaches Main or the marketplace.

• --dry-run prints the resolved execution order and mutates nothing.
• --yes / -y skips the confirmation prompt — use this for unattended runs. Branch validation still runs.
• --force / -f skips both the confirmation prompt and branch validation.
• --select restricts the run to named packages (repeatable). Deselecting an intermediate dependency will fail the run, since its dependents need the version it would have produced.
• --release-notes sets the notes for every republish; otherwise a summary of the re-pins is used.

A node whose dependencies are all already at their target version is skipped rather than republished for zero change, and its dependents treat it as a no-op instead of failing.

Publishing can block on a build, so the publish step uses the longer publish_timeout setting (default 300s) rather than api_timeout. If that call still times out, the version is confirmed by looking up the exact (package, version) pair in the marketplace — the record is committed before the build runs, so a timed-out publish has usually still landed.

cascade run and reference set are both blocked when DXS_RESTRICTED_MODE=true.

Repository Management (dxs source repo)

# List repos with branch info
dxs source repo list --with-branches

# Filter by type
dxs source repo list --type web

Service Pack Management (dxs source servicepack)

Service packs enable hotfix/maintenance branches from published releases.

# Create service pack for hotfixes
dxs source servicepack create --repo 10 --description "Q1 2024 Hotfixes"

Exploration (dxs source explore)

Commands for exploring application structure and dependencies.

Exploration Workflow:

# 1. Get application overview
dxs source explore info --branch 12345

# 2. List configurations (optionally filter)
dxs source explore configs --branch 12345 --type flow

# 3. View structural summary
dxs source explore summary create_order --branch 12345

# 4. Trace dependencies
dxs source explore trace create_order --branch 12345 --depth 3

See Agent Guide for detailed exploration workflows.

Documentation Generation (dxs source document)

Commands for bulk documentation and analysis.

Analysis Workflow:

# Initialize (downloads configs, builds graph)
dxs source document analyze init -o ./exploration --branch 12345

# Get next batch to analyze
dxs source document analyze next -o ./exploration --limit 5

# Store analysis result
dxs source document analyze store -o ./exploration -c local/flow/my_flow.yaml -f analysis.yaml

# Check progress
dxs source document analyze status -o ./exploration --by-type

See Analysis Workflow for detailed instructions.

Organizations (dxs organization)

Environments (dxs env)

# List environments
dxs env list --org 1

# Deploy to component
dxs env deploy 123 --force

Users (dxs user)

# Search users
dxs user list --search "john"

# Grant studio access
dxs user studio-access --user-id 123 --grant

CRM Integration (dxs crm)

Commands for Dynamics CRM integration.

Case Commands (dxs crm case):

# Search cases
dxs crm case search "payment error" --status active --limit 10

# Query with OData
dxs crm case query --filter "createdon gt 2024-01-01" --select title,ticketnumber

Account Commands (dxs crm account):

Metadata Commands (dxs crm metadata):

# List entities
dxs crm metadata entities

# Show incident fields
dxs crm metadata incident --relationships

OData Schema Discovery (dxs schema)

Progressively explore unfamiliar OData APIs and build efficient queries without guessing. Designed for token-efficient discovery with server-side filtering.

List Commands (add --count flag for count-only queries):

Describe Commands (detailed views):

Other Commands:

Progressive Discovery Workflow:

# 1. SEARCH FIRST (most efficient - returns ~20 matches)
dxs schema search "invoice" -c 1

# 2. DESCRIBE structure (understand properties and keys)
dxs schema describe-entity Invoices -c 1 | grep -A 50 "navigation_properties:"

# 3. EXPLORE relationships (find what can be expanded)
dxs schema describe-relationships Invoices -c 1

# 4. TEST queries incrementally (avoid 400 errors)
dxs odata execute -c 1 -q "Invoices(123)?\$expand=InvoiceLines"

Real-World Example: Build a Complete Invoice Report

Following the progressive workflow above, you can retrieve a complete invoice with all line items, rates, and lookup data in 1 HTTP call:

dxs odata execute -c 1 -q "BillingContracts(5763)?\$expand=Status,Currency,BillingContractType,BillingContractLines(\$expand=BillingRates,ResultingBillingCode,BillingAggregationStrategy)"

This nested expansion returns:

• Invoice header (dates, amounts, IDs)
• Status lookup ("Active")
• Currency lookup ("USD")
• Contract type ("ByProject")
• 5 line items, each with:
  • Billing rates (pricing rules)
  • Billing codes (charge categories)
  • Aggregation strategies (billing methods)

Token-Efficient Discovery Tips:

# DON'T: List all entities (returns thousands)
dxs schema entities -c 1  # ~5000 tokens

# DO: Search for specific entities (returns ~20 matches)
dxs schema search "order" -c 1  # ~200 tokens

# Use --count flag for count-only queries (minimal tokens)
dxs schema entities --count -c 1        # Returns: count: 150
dxs schema search "invoice" --count -c 1  # Returns: count: 10

# Filter large describe output with grep
dxs schema describe-entity EntityName -c 1 | grep -A 50 "navigation_properties:"

# Save large schemas to file for analysis
dxs schema describe-entity EntityName -c 1 > schema.yaml 2>&1

Query Building Best Practices:

✅ Always check navigation properties exist before $expand ✅ Test $expand incrementally: single → multiple → nested ✅ Use $select to limit fields: Entity?$select=Id,Name,Date ✅ Use bulk queries: Entity?$filter=Id in (1,2,3) vs one-by-one ✅ Start with schema search (not entities) when looking for entities

See Schema Discovery Guide for command reference and Schema Discovery Examples for complete real-world walkthroughs.

OData Queries (dxs odata)

# Simple query
dxs odata execute -c 1 -q "Warehouses?\$top=5"

# Query with filter and expand
dxs odata execute -c 1 -q "Orders?\$filter=Id eq 100&\$expand=OrderLines"

# Select specific fields
dxs odata execute -c 1 -q "Products?\$select=Id,Name,Price&\$top=10"

Marketplace (dxs marketplace)

list and search mirror the Manager > Marketplace screen: they show packages available to a consumer organization, each with an included flag indicating whether that org already has access.

• --type selects the marketplace application type, defaulting to componentmodule. Other types (web, mobile, api, portal, footprintapi, taskscheduler) are accepted but are not what the Marketplace screen shows.
• --org is the consumer organization being browsed on behalf of, not a result filter. Omit it to browse as your own organization.

Azure DevOps (dxs devops)

# Get work item with relations
dxs devops workitem 12345 --org my-org --expand Relations

# Batch fetch with descriptions
dxs devops workitems "123,456,789" --org my-org --description

Raw API (dxs api)

Make direct API requests with automatic authentication.

# GET request
dxs api GET /organizations/mine

# POST request
dxs api POST /some/endpoint '{"key": "value"}'

# PUT request
dxs api PUT /some/endpoint '{"data": "value"}'

Global Options

Further Documentation

For AI Agents

• Agent Guide - Detailed exploration workflows for analyzing Datex Studio applications
• Schema Discovery Guide - Progressive OData model exploration and query building techniques
• Schema Discovery Examples - Real-world walkthroughs with complete workflows, metrics, and troubleshooting

For Human Users

• Analysis Workflow - Bulk analysis workflow documentation
• Claude Code Telemetry Collector - Team-wide Claude Code observability: OTel collector → Datadog, rolled out from the claude.ai admin console

Development

# Clone and install
git clone https://github.com/datex/datex-studio-cli.git
cd datex-studio-cli
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Run tests
pytest

# Lint and format
ruff check .
ruff format .

# Type check
mypy src/dxs

License

MIT