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 is stored in ~/.datex/config.yaml. Credentials use the existing local files by default: ~/.datex/credentials.yaml and ~/.datex/proxy_tokens.json. Tokens in this mode are plaintext; daemon secrets retain machine-local obfuscation. Native-vault encryption is available as an opt-in:

dxs settings set credential_storage keychain
dxs auth login

# Opt out if the native vault causes problems, then sign in again:
dxs settings set credential_storage file
dxs auth login

An existing DXS_CREDENTIAL_STORAGE environment variable overrides the saved setting; remove it or change it to the desired mode. Restart running CLI/proxy processes when changing modes. Use DXS_CREDENTIAL_STORAGE=memory for process-only operation. See credential storage for platform setup, migration, cleanup, recovery and native validation.

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 create and cascade run require the Wavelength API's POST /api/sourcecontrol/{id}/featureBranch route (API PR 4856, October 9, 2026). Upgrade older API deployments before using these commands; the CLI does not fall back to the removed createFeatureBranch route or retry branch creation. See the unreleased change notes.

Detailed commit notes:

dxs source branch commit 3101 --title "Fix allocation" \
  --description "Prevent duplicate allocation." \
  --release-notes-file commit-notes.md --all-changes

# Retrieve the notes with commit metadata
dxs -O json source log --branch 3101
dxs -O yaml source history userGrid --branch 3101 --diff
dxs source branch show 3101

Use either --release-notes TEXT or --release-notes-file PATH (UTF-8). The CLI sends the exact supplied text as releaseNotes, separately from the required short description. Markdown, Unicode, indentation, hard-break spaces, and original line endings are preserved. Conflicting options, unreadable files, and invalid UTF-8 fail before any commit request. --dry-run previews the supplied notes as commitReleaseNotes without mutation.

Omitting both options leaves releaseNotes out of the request. The API falls back to description when notes are absent, empty, or whitespace-only. Log, history, and branch-detail results expose commitReleaseNotes separately from commitMessage / commitDescription. JSON and YAML preserve this text exactly; YAML quotes it to preserve significant whitespace and Unicode line separators. Missing fields from older APIs are accepted; null fields appear with global --full and are omitted in default concise output. These notes belong to one commit; branch publish --notes and cascade publication notes describe a marketplace release and remain separate.

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

# Activate a selected version (confirms the destination and version first)
dxs env deploy 123 --definition-id 456

Both IDs must be positive integers. The component ID identifies an existing environment component/version belonging to the destination definition; it is not a marketplace version ID or an application/branch ID. Inactive versions can be activated. The command does not select a version implicitly or import a version. The former one-ID invocation now requires --definition-id.

To discover the IDs through supported read endpoints:

# Destination definitions in an environment; use a returned definition's id
dxs api get '/environmentcomponentdefinitions?environmentId=15'
# Versions belonging to that definition; use a returned component's id
dxs api get /environmentcomponentdefinitions/456/components

Deployment requires a per-user Deploy Access (HasDeployAccess) grant from an authorized Datex administrator, including for Datex users. On rollout this grant defaults to false without a backfill; Manager/Studio access does not imply it. Refreshing credentials or updating the CLI does not supply the grant. --force only skips confirmation; target validation, organization checks, restricted mode, and server authorization still apply.

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)

# Create a work item (uses default_devops_org when --org is omitted)
dxs devops create --org my-org --project MyProject --type Bug --title "Fix login"

# Include a description, parent, assignee, and additional fields
dxs devops create --project MyProject --type Task --title "Add login tests" \
  --description-file description.html --parent 12345 --assigned-to dev@example.com \
  --tags "cli; testing" --field Microsoft.VSTS.Common.Priority=2

# 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

# Discover projects using the default organization, or override it
dxs devops projects
dxs devops projects --search footprint
dxs devops projects --org my-org --search mobile

projects lists accessible active projects across all result pages. --search matches a case-insensitive substring of the project name. Results include project IDs and names usable with --project. Omitting --org uses default_devops_org (or DXS_DEFAULT_DEVOPS_ORG); an unset default produces an error.

Creation returns the work item's ID, URL, and details. Project, type, and title are required; type names depend on the project's process (for example, Bug, Task, or "User Story"). Optional --area-path and --iteration-path set classification. Use either --description or --description-file (UTF-8); content is sent as supplied to Azure DevOps's HTML description field, without Markdown conversion. Repeat --field NAME=VALUE for additional field reference names; values are sent as strings, and duplicate fields are rejected. Azure DevOps validates required fields and permissions using the existing signed-in identity.

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

• CLI Security White Paper - Review draft covering Entra consent, authentication, connectors, credential storage, and operational controls. PDF | Word. Updated for opt-in native-vault storage at source revision 4a09d36; confirm the deployed build and remaining validation before relying on it.
• Entra Security Overview - Reusable explanation of tenant access, consent, permissions, and credential handling
• Security White Paper - Claude Code business case, recorded enterprise-app details, and proposed change-control plan. PDF | Word
• 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

Diagnose installation problems

Use dxs doctor to check the Python actually running dxs, installation/PATH, release compatibility and saved credential readability. dxs doctor --fix can repair a verified uv tool environment; add --yes for automation. dxs update also handles releases that require a newer Python. See installation health and Python upgrades.