Skip to content

INSTALLATION.md

Latest commit

 

History

History
480 lines (329 loc) · 11.1 KB

INSTALLATION.md

File metadata and controls

480 lines (329 loc) · 11.1 KB

Installing dtctl

This guide covers installing dtctl on your system.

Homebrew (Recommended — macOS and Linux)

brew install dynatrace-oss/tap/dtctl

This installs the binary and sets up shell completions (bash, zsh, fish) automatically.

To upgrade:

brew upgrade dtctl

To uninstall:

brew uninstall dtctl
brew untap dynatrace-oss/tap  # optional

Shell Script (macOS and Linux)

If you don't use Homebrew, install with a single command:

curl -fsSL https://raw.githubusercontent.com/dynatrace-oss/dtctl/main/install.sh | sh

This downloads the latest release, extracts it to ~/.local/bin (Linux) or /usr/local/bin (macOS), and verifies the installation.

Override the install directory with DTCTL_INSTALL_DIR:

curl -fsSL https://raw.githubusercontent.com/dynatrace-oss/dtctl/main/install.sh | DTCTL_INSTALL_DIR=~/bin sh

To update, re-run the same command.

Windows (PowerShell)

irm https://raw.githubusercontent.com/dynatrace-oss/dtctl/main/install.ps1 | iex

This downloads the latest release, extracts it to %LOCALAPPDATA%\dtctl, and adds it to your PATH. Restart your terminal (or IDE) afterwards for the PATH change to take effect.

For detailed steps, manual install, PowerShell tips, quoting, and troubleshooting, see the dedicated Windows installation guide.

Binary Download

For most users, download the pre-built binary for your platform:

  1. Download the latest release: Visit the releases page and download the appropriate binary for your operating system and architecture.

  2. Extract and install:

    Linux/macOS:

    # Extract the archive
tar -xzf dtctl_*.tar.gz

# Make it executable
chmod +x dtctl

# macOS only: Remove quarantine attribute (see Troubleshooting section for details)
sudo xattr -r -d com.apple.quarantine dtctl

# Move to a directory in your PATH
sudo mv dtctl /usr/local/bin/

# Verify installation
dtctl version

  3. Next Steps: See the Quick Start Guide to configure your environment.

Building from Source (Advanced)

For developers who want to build from source or contribute to the project.

Prerequisites

  • Go 1.24 or later
  • Git
  • Make

Clone and Build

# Clone the repository
git clone https://github.com/dynatrace-oss/dtctl.git
cd dtctl

# Build the binary
make build

# Verify the build
./bin/dtctl version

Expected output:

dtctl version dev
commit: unknown
built: unknown

Test the Binary

Try a few commands to ensure everything works:

# Show help
./bin/dtctl --help

# View available commands
./bin/dtctl get --help
./bin/dtctl query --help

# Run health check (after configuration)
./bin/dtctl doctor

Installation Options (Source Builds)

Option 1: Use from bin/ Directory

The simplest approach - use ./bin/dtctl directly:

# From the project directory
./bin/dtctl config set-context my-env \
  --environment "https://YOUR_ENV.apps.dynatrace.com" \
  --token-ref my-token

Option 2: Install to GOPATH

Install to your Go binary directory:

make install

# Verify
dtctl version

This installs to $GOPATH/bin/dtctl (typically ~/go/bin/dtctl). Ensure $GOPATH/bin is in your $PATH.

# Add Go bin to PATH (zsh/bash)
export PATH="$PATH:$(go env GOPATH)/bin"

Option 3: Copy to System PATH

Install system-wide:

# Linux/macOS
sudo cp bin/dtctl /usr/local/bin/

# Verify
dtctl version

Option 4: Add to PATH

Add the bin directory to your PATH:

# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export PATH="$PATH:/path/to/dtctl/bin"

# Reload your shell
source ~/.bashrc  # or ~/.zshrc

Shell Completion (Optional)

Enable tab completion for faster workflows.

Bash

# Generate completion script
dtctl completion bash > /tmp/dtctl-completion.bash

# Test it
source /tmp/dtctl-completion.bash

# Make it permanent
sudo mkdir -p /etc/bash_completion.d
sudo cp /tmp/dtctl-completion.bash /etc/bash_completion.d/dtctl

# Reload your shell
source ~/.bashrc

Zsh

# Create completions directory
mkdir -p ~/.zsh/completions

# Generate completion script
dtctl completion zsh > ~/.zsh/completions/_dtctl

# Add to your ~/.zshrc (if not already present)
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
echo 'autoload -U compinit && compinit' >> ~/.zshrc

# Clear completion cache and reload
rm -f ~/.zcompdump*
source ~/.zshrc

For oh-my-zsh users: Place the completion file in ~/.oh-my-zsh/completions/_dtctl:

mkdir -p ~/.oh-my-zsh/completions
dtctl completion zsh > ~/.oh-my-zsh/completions/_dtctl
rm -f ~/.zcompdump*
source ~/.zshrc

Fish

# Create completions directory (if needed)
mkdir -p ~/.config/fish/completions

# Generate completion script
dtctl completion fish > ~/.config/fish/completions/dtctl.fish

# Reload shell
source ~/.config/fish/config.fish

PowerShell

# Temporary (current session)
dtctl completion powershell | Out-String | Invoke-Expression

# Permanent - add to your PowerShell profile
# First, find your profile location:
echo $PROFILE

# Then add this line to your profile:
dtctl completion powershell | Out-String | Invoke-Expression

Verify Installation

After installation, verify everything works:

# Check version
dtctl version

# View help
dtctl --help

# Test tab completion (if enabled)
dtctl get <TAB><TAB>

Updating dtctl

If Installed via Homebrew

brew update
brew upgrade dtctl

If Installed from Release

Download and install the latest release following the Binary Download steps above.

If Built from Source

To update to the latest version:

# Navigate to the repository
cd /path/to/dtctl

# Pull latest changes
git pull

# Rebuild
make build

# Reinstall (if using Option 2 or 3)
make install
# or
sudo cp bin/dtctl /usr/local/bin/

Uninstalling

To remove dtctl:

Windows (PowerShell)

# Remove binary + PATH entry
irm https://raw.githubusercontent.com/dynatrace-oss/dtctl/main/uninstall.ps1 | iex

# Optional: full cleanup (config/cache/data)
irm https://raw.githubusercontent.com/dynatrace-oss/dtctl/main/uninstall.ps1 -OutFile uninstall-dtctl.ps1
.\uninstall-dtctl.ps1 -RemoveConfig -RemoveCache -RemoveData

macOS/Linux

# If installed via Homebrew
brew uninstall dtctl

# If installed via Option 2 (make install)
rm $GOPATH/bin/dtctl

# If installed via Option 3 (system-wide)
sudo rm /usr/local/bin/dtctl

# Remove configuration (optional)
rm -rf ~/.config/dtctl    # Linux
# or
rm -rf ~/Library/Application\ Support/dtctl    # macOS

Next Steps

Now that dtctl is installed, see the Quick Start Guide to learn how to:

  • Configure your Dynatrace environment
  • Execute commands
  • Work with workflows, dashboards, DQL queries, and more

Troubleshooting

"command not found: dtctl"

The binary is not in your PATH. Either:

  1. Use the full path: ./bin/dtctl or /path/to/dtctl/bin/dtctl
  2. Add the bin directory to your PATH (see Option 4 above)
  3. Install to a directory already in PATH (see Options 2 or 3 above)

Check your PATH:

echo $PATH

"permission denied"

Make the binary executable:

chmod +x bin/dtctl

macOS: "Apple could not verify dtctl is free of malware"

When downloading pre-built binaries on macOS, you may see this security warning:

"dtctl" cannot be opened because Apple cannot verify that it is free of malware.

This is expected behavior for unsigned binaries. The dtctl releases are not code-signed with an Apple Developer ID certificate, which is common for open-source CLI tools.

Option 1: Remove quarantine attribute (Recommended)

# Remove the quarantine flag
sudo xattr -r -d com.apple.quarantine dtctl

# Then make it executable
chmod +x dtctl

Option 2: Allow via System Settings

  1. Try to run ./dtctl
  2. When the warning appears, click "Cancel"
  3. Open System Settings > Privacy & Security
  4. Scroll to the Security section at the bottom
  5. Click "Allow Anyway" next to the dtctl message
  6. Try running ./dtctl again and click "Open" when prompted

Why does this happen?

macOS Gatekeeper adds a com.apple.quarantine extended attribute to files downloaded from the internet. When you try to execute them, macOS checks for:

  • Code signing by a registered Apple Developer ID
  • Notarization by Apple (malware scanning)

Since dtctl is an open-source project and not signed/notarized, macOS blocks it by default. The workarounds above tell macOS you trust this binary.

Is this safe?

Yes, if you downloaded dtctl from the official GitHub releases page. Always verify:

  • You're downloading from github.com/dynatrace-oss/dtctl
  • The checksum matches (see checksums.txt in the release)

Note: If you build from source locally, this issue doesn't occur since the binary isn't quarantined.

Build fails

Ensure you have the required prerequisites:

# Check Go version (needs 1.24+)
go version

# Check Make
make --version

# Try cleaning and rebuilding
make clean
make build

Shell completion not working

After setting up completion:

  1. Ensure you reloaded your shell or sourced the config file
  2. Clear completion cache (Zsh: rm -f ~/.zcompdump*)
  3. Verify the completion file exists in the correct location
  4. Check file permissions: ls -la ~/.zsh/completions/_dtctl

Getting Help

macOS: "zsh: exec format error"

If you built the binary inside a Linux-based devcontainer (for example on an ARM container) and then try to run bin/dtctl natively on macOS, you may see:

zsh: exec format error: bin/dtctl

This happens because the compiled binary's OS/architecture don't match your host. To fix it, rebuild the binary for macOS on your host or produce a cross-compiled macOS binary.

Rebuild locally on macOS (recommended):

# From the project root
make clean
# Build for the host (native macOS build)
make build-host
# Or explicitly build for darwin/arm64
make build-darwin-arm64

# Run the built binary
./bin/dtctl-host version    # from `make build-host`
# or
./bin/dtctl-darwin-arm64 version

Cross-build from Linux (requires Go on the build machine):

# Create a darwin/arm64 binary from Linux
env GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -o bin/dtctl-darwin-arm64 .

Notes:

  • If you built the binary inside a container using a different OS (Linux) and then copied it to macOS, the binary won't run on macOS. Always build for the target OS/arch.
  • For Apple Silicon (arm64) Macs, target darwin/arm64. For older Intel Macs target darwin/amd64.
  • If you need universal binaries or native macOS toolchain features, build on macOS directly.