# 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

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

# Using pip
pip install datex-studio-cli
```

## Quick Start

```bash
# 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:

```yaml
# 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:

```bash
# 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:

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

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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 |

```bash
# 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 |

```bash
# 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:**

```bash
# 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](docs/agent-guide.md) 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:**

```bash
# 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](docs/analysis-workflow.md) 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 |

```bash
# 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 |

```bash
# 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 |

```bash
# 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 |

```bash
# 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:**

```bash
# 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**:

```bash
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:**

```bash
# 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](docs/schema-discovery-guide.md) for command reference and [Schema Discovery Examples](docs/schema-discovery-examples.md) for complete real-world walkthroughs.

### OData Queries (`dxs odata`)

| Command | Description |
|---------|-------------|
| `execute` | Execute OData query against Footprint API |

```bash
# 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 |

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

```bash
# 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](docs/agent-guide.md)** - Detailed exploration workflows for analyzing Datex Studio applications
- **[Schema Discovery Guide](docs/schema-discovery-guide.md)** - Progressive OData model exploration and query building techniques
- **[Schema Discovery Examples](docs/schema-discovery-examples.md)** - Real-world walkthroughs with complete workflows, metrics, and troubleshooting

### For Human Users

- **[Analysis Workflow](docs/analysis-workflow.md)** - Bulk analysis workflow documentation

## Development

```bash
# 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
