DMtools Configuration Guide

Configuration Overview

DMtools uses a hierarchical configuration system with multiple sources. Configuration is loaded in priority order (highest to lowest):

1. Environment Variables - Set in your shell or system
2. dmtools.env - Local configuration file (current directory)
3. dmtools-local.env - User-specific configuration
4. application.properties - Server configuration (Spring Boot)

Configuration Methods

Method 1: Environment Variables (Recommended for CI/CD)

# Export in your shell
export JIRA_BASE_PATH=https://company.atlassian.net
export JIRA_LOGIN_PASS_TOKEN=$(echo -n "email@company.com:token" | base64)
export GEMINI_API_KEY=your-api-key

# Run DMtools
dmtools list

Method 2: dmtools.env File (Recommended for Development)

Create a dmtools.env file in your project directory:

# dmtools.env
JIRA_BASE_PATH=https://company.atlassian.net
JIRA_LOGIN_PASS_TOKEN=base64_encoded_credentials
JIRA_AUTH_TYPE=Bearer

# AI Provider (choose one)
GEMINI_API_KEY=your-gemini-api-key
#OPEN_AI_API_KEY=sk-...
#DIAL_API_KEY=...

# Azure DevOps
ADO_BASE_PATH=https://dev.azure.com/organization
ADO_PAT=your-personal-access-token
ADO_PROJECT=YourProject

# GitHub
SOURCE_GITHUB_TOKEN=ghp_...
SOURCE_REPO_PATH=/path/to/local/repo

# Figma
FIGMA_ACCESS_TOKEN=your-figma-token

Method 3: dmtools-local.env (User-specific)

For personal settings that shouldn’t be committed:

# ~/.dmtools/dmtools-local.env
# Personal tokens and keys
JIRA_LOGIN_PASS_TOKEN=your_personal_token
GEMINI_API_KEY=your_personal_key

Essential Configuration Variables

Core Settings

CLI Logging and Transcripts

When DMTools runs in normal CLI mode, most Java-side logging is suppressed to keep output clean. Use these variables to control CLI command output visibility and persistence.

Selective CLI output with DMTOOLS_CLI_LOG_FILTER

Use this variable to make specific long-running CLI commands visible without enabling all debug logging.

# Tee run-agent.sh output to console and file
DMTOOLS_CLI_LOG_FILTER=run-agent ./dmtools.sh run agents/story_development.json

# Match multiple command patterns
DMTOOLS_CLI_LOG_FILTER=run-agent,cursor-agent,dmtools run ./dmtools.sh run agents/pr_review.json

How it works:

• Matching is case-insensitive and ignores surrounding whitespace.
• When a command matches, every line of its output is printed to the console even if log4j2-cli.xml would otherwise suppress logs.
• The same output is also written to a timestamped transcript file under DMTOOLS_CLI_LOG_DIR (default: .dmtools-logs/cli).
• In --debug mode the console output is already visible, so the filter only avoids duplication there; the transcript file is still written.

This covers commands executed both as Teammate cliCommands and via the cli_execute_command MCP tool from JavaScript actions.

Integration Credentials

AI Provider Configuration

Configure at least one AI provider:

Configuration File Examples

Minimal Configuration (Jira + Gemini)

# dmtools.env - Minimal setup
JIRA_BASE_PATH=https://mycompany.atlassian.net
JIRA_LOGIN_PASS_TOKEN=<your-base64-encoded-email:api-token>
GEMINI_API_KEY=YOUR_GEMINI_API_KEY_HERE

Full Development Configuration

# dmtools.env - Complete development setup
# Jira Configuration
JIRA_BASE_PATH=https://mycompany.atlassian.net
JIRA_LOGIN_PASS_TOKEN=<your-base64-encoded-email:api-token>
JIRA_AUTH_TYPE=Bearer
JIRA_FIELDS_MAPPING=customfield_10001:StoryPoints,customfield_10002:Epic

# Azure DevOps
ADO_BASE_PATH=https://dev.azure.com/myorg
ADO_PAT=YOUR_ADO_PERSONAL_ACCESS_TOKEN
ADO_PROJECT=MyProject
ADO_AREA_PATH=MyProject\\Backend
ADO_ITERATION_PATH=MyProject\\Sprint 23

# AI Providers (multiple configured, runtime selection)
GEMINI_API_KEY=YOUR_GEMINI_API_KEY_HERE
GEMINI_MODEL=gemini-2.0-flash
OPEN_AI_API_KEY=YOUR_OPENAI_API_KEY_HERE
OPEN_AI_MODEL=gpt-4o

# Source Control
SOURCE_GITHUB_TOKEN=YOUR_GITHUB_TOKEN_HERE
SOURCE_REPO_PATH=/Users/me/projects/myapp
SOURCE_ORG=mycompany

# Figma
FIGMA_ACCESS_TOKEN=YOUR_FIGMA_ACCESS_TOKEN_HERE
FIGMA_FILE_KEY=ABC123XYZ

# Confluence
CONFLUENCE_BASE_PATH=https://mycompany.atlassian.net/wiki
CONFLUENCE_LOGIN_PASS_TOKEN=<your-base64-encoded-email:api-token>
CONFLUENCE_SPACE_KEY=DOCS

# Performance Tuning
PROMPT_CHUNK_TOKEN_LIMIT=4000
PROMPT_CHUNK_MAX_SINGLE_FILE_SIZE_MB=4

CI/CD Configuration

# .github/workflows/dmtools.yml
env:
  JIRA_BASE_PATH: ${{ secrets.JIRA_BASE_PATH }}
  JIRA_LOGIN_PASS_TOKEN: ${{ secrets.JIRA_TOKEN }}
  GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

Security Best Practices

1. Never Commit Credentials

# .gitignore
dmtools.env
dmtools-local.env
*.env
.env*

2. Use Base64 Encoding for Jira

# Encode credentials
echo -n "email@company.com:api_token" | base64
# Output: <your-base64-encoded-email:api-token>

# Set in configuration
JIRA_LOGIN_PASS_TOKEN=<your-base64-encoded-email:api-token>

3. Rotate Tokens Regularly

• API tokens should be rotated every 90 days
• Use separate tokens for dev/staging/production
• Revoke unused tokens immediately

4. Use Environment-Specific Files

dmtools.env.development
dmtools.env.staging
dmtools.env.production

5. Secure Storage Options

For production environments, consider:

• AWS Secrets Manager
• HashiCorp Vault
• Azure Key Vault
• Kubernetes Secrets

Testing Configuration

Verify Jira Connection

# Test Jira access
dmtools jira_get_ticket PROJ-123

# Search tickets
dmtools jira_search_by_jql "project = PROJ AND status = Open"

Verify AI Provider

# Test Gemini
dmtools gemini_ai_chat "Hello, are you working?"

# Test OpenAI
dmtools openai_ai_chat "Hello, are you working?"

Verify Azure DevOps

# Get work item
dmtools ado_get_work_item 12345

# List iterations
dmtools ado_get_iterations

List All Configured Tools

# Show all available MCP tools
dmtools list

# Should display 67+ tools if all integrations are configured

Configuration Precedence Examples

# Scenario 1: Environment variable overrides file
export GEMINI_API_KEY=env-key
# dmtools.env contains: GEMINI_API_KEY=file-key
# Result: env-key is used

# Scenario 2: dmtools.env overrides dmtools-local.env
# dmtools.env: JIRA_BASE_PATH=https://prod.atlassian.net
# dmtools-local.env: JIRA_BASE_PATH=https://dev.atlassian.net
# Result: https://prod.atlassian.net is used

# Scenario 3: Check active configuration
dmtools --show-config  # Shows resolved configuration

Configuration for Different Workflows

Test Case Generation Setup

# Required for test generation
JIRA_BASE_PATH=https://company.atlassian.net
JIRA_LOGIN_PASS_TOKEN=...
GEMINI_API_KEY=...  # Or other AI provider

# Optional for enhanced features
JIRA_XRAY_CLIENT_ID=...  # For Xray integration
CONFLUENCE_BASE_PATH=...  # For documentation

Code Generation Setup

# Required
SOURCE_GITHUB_TOKEN=...
SOURCE_REPO_PATH=/path/to/repo
OPEN_AI_API_KEY=...  # GPT-4 recommended for code

# Optional
SONAR_TOKEN=...  # For code quality checks

Documentation Generation Setup

# Required
CONFLUENCE_BASE_PATH=...
CONFLUENCE_LOGIN_PASS_TOKEN=...
CONFLUENCE_SPACE_KEY=DOCS

# AI provider for content generation
GEMINI_API_KEY=...

Next Steps

1. Choose your integrations - Start with Jira and one AI provider
2. Create dmtools.env - Copy examples above and add your credentials
3. Test connections - Run test commands to verify setup
4. Explore specific guides:
   • Jira Configuration
   • Gemini AI Setup
   • Azure DevOps Setup
   • CLI Output Formats

Troubleshooting

Common configuration issues:

Need help? Check integration-specific guides or report issues at github.com/epam/dm.ai/issues