datex-studio-cli 0.4.6

CLI for Datex Studio low-code platform, designed for LLM-based AI agents

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
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

Variable	Description
DXS_ORG	Default organization ID
DXS_ENV	Default environment ID
DXS_BRANCH	Default branch ID
DXS_REPO	Default repository ID
DXS_API_BASE_URL	API base URL
DXS_RESTRICTED_MODE	Enable restricted mode (blocks destructive commands)

Config File

# View current configuration
dxs config list

# Set a default
dxs config set default_repo 10

# Get a specific value
dxs config 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)

Command	Description
login	Authenticate with Azure Entra (device code flow)
logout	Clear credentials (--all for all identities)
status	Show current authentication status and token expiration
list	List all cached identities
switch <identity>	Switch to a different cached identity

Multi-Identity Workflow:

# Login to primary organization
dxs auth login

# Login to additional organization (prompts for new auth)
dxs auth login --org other-org

# List all identities
dxs auth list

# Switch between organizations
dxs auth switch other-org

Configuration (dxs config)

Command	Description
get <key>	Get a configuration value
set <key> <value>	Set a configuration value
list	List all configuration values with sources

Source Control (dxs source)

Direct commands on the source group:

Command	Description
status	Show branch status summary
log	Show commit history
history <ref>	Show configuration version history
diff	Show pending changes (draft vs committed)
changes	Show pending changes in detail
locks	Show current lock status
deps <ref>	Show configuration dependencies
deps-diff	Show dependency changes between versions
workitems	Extract work items from commit messages
compare	Compare two branches
graph	Show dependency graph

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)

Command	Description
list	List branches (with filtering options)
show <id>	Show branch details
create	Create a new feature branch
delete <id>	Delete a feature branch
publish <id>	Publish branch to marketplace
baseline <id>	Find baseline (previous release)
search <query>	Search branches by name
roles <id>	Show branch roles
shell <id>	Show shell configuration
validate <id>	Validate branch configuration
candelete <id>	Check if branch can be deleted
settings <id>	List application settings
operations <id>	List operations and workflows
replacements <id>	List configuration replacements

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

Repository Management (dxs source repo)

Command	Description
list	List repositories
show <id>	Show repository details
search <query>	Search repositories by name

# 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.

Command	Description
list	List service pack groups
create	Create service pack from published version
delete <id>	Delete service pack group

# 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.

Command	Description
info	Show application overview
configs	List all configurations
config <ref>	View a specific configuration
summary <ref>	Show structural summary
trace <ref>	Trace configuration dependencies
graph	Generate dependency graph
cache	Manage exploration cache
manifest	Show application manifest
extract-code	Extract code from configurations
verify	Verify configuration integrity
summarize	Generate configuration summaries

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.

Command	Description
build	Download configurations with context generation
resume	Resume interrupted build
status	Show documentation build status
graph	Generate dependency graph from local files
analyze init	Initialize analysis workflow
analyze next	Get next batch of configs to analyze
analyze store	Store analysis result
analyze status	Show analysis progress

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)

Command	Description
list	List all organizations
show <id>	Show organization details
mine	Show current user's organization
search <query>	Search organizations

Environments (dxs env)

Command	Description
list	List environments
components	List environment components
deploy <component_id>	Deploy to an environment component
list-authorized	List components user has access to

# List environments
dxs env list --org 1

# Deploy to component
dxs env deploy 123 --force

Users (dxs user)

Command	Description
list	List all users
studio-access	Grant/revoke studio access

# 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):

Command	Description
search	Search support cases
query	Execute OData query against cases

# 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):

Command	Description
list	List accounts
search <query>	Search accounts by name

Metadata Commands (dxs crm metadata):

Command	Description
entities	List all available entities
<entity_name>	Show fields for an entity

# 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):

Command	Description	Performance
search <keyword>	Search entities by name (server-side filtered)	~200 tokens, <1s
entities	List all entities in the model	~5000 tokens, <1s
enums	List enumeration types	~500 tokens, <1s
actions	List server-side actions (POST operations)	~300 tokens, <1s
functions	List server-side functions (GET operations)	~300 tokens, <1s
complex-types	List complex types (structured non-entities)	~200 tokens, <1s
singletons	List singletons (single-instance entities)	~100 tokens, <1s

Describe Commands (detailed views):

Command	Description	Performance
describe-entity <entity>	Show full entity schema (properties, types, navigation)	1,000-50,000 tokens, <2s
describe-relationships <entity>	Show navigation properties and relationships	~1000 tokens, <2s
describe-properties <type> <prop>	Show details for a specific property (by composite key)	~100 tokens, <1s
describe-navigation-properties <type> <prop>	Show details for a specific navigation property (by composite key)	~100 tokens, <1s
describe-enum <enum>	Show enum members and values	~200 tokens, <1s
describe-action <action>	Show action parameters and return type	~300 tokens, <1s
describe-function <func>	Show function parameters and return type	~300 tokens, <1s
describe-complex-type <type>	Show complex type structure	~200 tokens, <1s
describe-singleton <singleton>	Show singleton details	~500 tokens, <1s

Other Commands:

Command	Description	Performance
metadata	Get raw OData metadata (EDMX XML)	Large, <2s

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)

Command	Description
execute	Execute OData query against Footprint API

# 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)

Command	Description
list	List marketplace applications
show <id>	Show application details
versions <id>	List published versions
version <id>	Show version details
search <query>	Search applications

Azure DevOps (dxs devops)

Command	Description
workitem <id>	Get single work item
workitems <ids>	Get multiple work items (batch)
search <query>	Search work items

# 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

Option	Description
-o, --org	Organization ID
-e, --env	Environment ID
-b, --branch	Branch ID
-r, --repo	Repository ID
-O, --output	Output format: yaml, json, csv
-v, --verbose	Enable verbose output
-q, --quiet	Suppress progress messages
-f, --full	Show full output (disable concise mode)
-s, --save	Save output to file
--force	Force overwrite when saving

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

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