Skip to content

developer-tools.md

Latest commit

 

History

History
719 lines (542 loc) · 24.9 KB

developer-tools.md

File metadata and controls

719 lines (542 loc) · 24.9 KB

Developer Tool Integrations

Deep Integration: Not just aliases—helpers, completions, and workflow automation for your entire toolchain.

Blackdot provides deep integrations with modern developer tools. Each tool suite is feature-gated and can be enabled/disabled independently.

Quick Overview

Tool Suite Feature Flag Description
AWS Tools aws_helpers Profile switching, SSO login, identity display
CDK Tools cdk_tools Deploy, diff, synth with smart defaults
Rust Tools rust_tools Build, test, clippy, fmt, cargo-watch
Go Tools go_tools Build, test, coverage, module management
Python Tools python_tools uv package manager, pytest, auto-venv
SSH Tools ssh_tools Config, keys, agent, and tunnel management
Docker Tools docker_tools Container, compose, and network management
NVM nvm_integration Lazy-loaded Node.js version manager
SDKMAN sdkman_integration Lazy-loaded Java/Gradle/Kotlin manager

Total: 120+ aliases across all toolchains, with shell completions and helpers.

Cross-Platform Support

Shell Location Notes
Zsh (macOS/Linux) zsh/zsh.d/*.zsh Feature-gated, lazy-loaded
PowerShell (Windows) powershell/Blackdot.psm1 Equivalent aliases and functions

Most aliases work identically in both shells (gst, awswho, docker-ps, etc.). PowerShell users get the same tool integrations via the Blackdot module.

Feature Control

Each tool suite is independently toggleable:

# Enable/disable at runtime
blackdot features enable rust_tools
blackdot features disable cdk_tools

# Persist across sessions
blackdot features enable aws_helpers --persist
blackdot features disable go_tools --persist

# Check what's enabled
blackdot features list integration

AWS Tools

   █████╗ ██╗    ██╗███████╗    ████████╗ ██████╗  ██████╗ ██╗     ███████╗
  ██╔══██╗██║    ██║██╔════╝    ╚══██╔══╝██╔═══██╗██╔═══██╗██║     ██╔════╝
  ███████║██║ █╗ ██║███████╗       ██║   ██║   ██║██║   ██║██║     ███████╗
  ██╔══██║██║███╗██║╚════██║       ██║   ██║   ██║██║   ██║██║     ╚════██║
  ██║  ██║╚███╔███╔╝███████║       ██║   ╚██████╔╝╚██████╔╝███████╗███████║
  ╚═╝  ╚═╝ ╚══╝╚══╝ ╚══════╝       ╚═╝    ╚═════╝  ╚═════╝ ╚══════╝╚══════╝

Feature: aws_helpers | File: zsh/zsh.d/60-aws.zsh

Commands

Alias Description
awsprofiles List all AWS profiles from config
awsswitch Interactive profile switcher (uses fzf)
awswho Display current identity (aws sts get-caller-identity)
awslogin SSO login for current profile
awslogout SSO logout
awsset <profile> Set AWS_PROFILE directly
awsunset Unset AWS_PROFILE
awsassume <role-arn> Assume IAM role and export credentials
awsregion Display current region
awsregions List all available regions

Features

  • Automatic SSO login: awsswitch detects expired SSO sessions and prompts for login
  • fzf integration: Fuzzy-select from profiles with preview
  • Credential caching: Honors AWS credential cache for performance
  • Shell completions: awsswitch <TAB> completes profile names

Example Workflow

# Morning: login and switch to work profile
awsswitch                    # Fuzzy-select profile
# If SSO expired, auto-prompts: awslogin

# Check who you're authenticated as
awswho
# {
#   "UserId": "AROAEXAMPLE:john.doe@company.com",
#   "Account": "123456789012",
#   "Arn": "arn:aws:sts::123456789012:assumed-role/..."
# }

# Switch to different profile for deployment
awsset production
awswho                       # Verify

# End of day
awslogout

CDK Tools

   ██████╗██████╗ ██╗  ██╗    ████████╗ ██████╗  ██████╗ ██╗     ███████╗
  ██╔════╝██╔══██╗██║ ██╔╝    ╚══██╔══╝██╔═══██╗██╔═══██╗██║     ██╔════╝
  ██║     ██║  ██║█████╔╝        ██║   ██║   ██║██║   ██║██║     ███████╗
  ██║     ██║  ██║██╔═██╗        ██║   ██║   ██║██║   ██║██║     ╚════██║
  ╚██████╗██████╔╝██║  ██╗       ██║   ╚██████╔╝╚██████╔╝███████╗███████║
   ╚═════╝╚═════╝ ╚═╝  ╚═╝       ╚═╝    ╚═════╝  ╚═════╝ ╚══════╝╚══════╝
  AWS Cloud Development Kit

Feature: cdk_tools | File: zsh/zsh.d/61-cdk.zsh | Depends on: aws_helpers

Commands

Alias Description
cdkd cdk deploy with standard flags
cdkda cdk deploy --all
cdkdf cdk diff
cdkdfa cdk diff --all
cdks cdk synth
cdksa cdk synth --all
cdkls cdk list
cdkdestroy cdk destroy
cdkwatch cdk watch for hot-reload development
cdkboot cdk bootstrap
cdkdoc Open CDK docs
cdkctx cdk context

Features

  • Smart defaults: Common flags like --require-approval never for non-prod
  • Stack targeting: Easy --all variants for multi-stack apps
  • Watch mode: cdkwatch for rapid iteration
  • Context management: cdkctx helpers

Example Workflow

# Develop with hot-reload
cdkwatch

# Check what changed
cdkdf

# Deploy single stack
cdkd MyStack

# Deploy everything
cdkda

# Tear down
cdkdestroy MyStack

Rust Tools

  ██████╗ ██╗   ██╗███████╗████████╗    ████████╗ ██████╗  ██████╗ ██╗     ███████╗
  ██╔══██╗██║   ██║██╔════╝╚══██╔══╝    ╚══██╔══╝██╔═══██╗██╔═══██╗██║     ██╔════╝
  ██████╔╝██║   ██║███████╗   ██║          ██║   ██║   ██║██║   ██║██║     ███████╗
  ██╔══██╗██║   ██║╚════██║   ██║          ██║   ██║   ██║██║   ██║██║     ╚════██║
  ██║  ██║╚██████╔╝███████║   ██║          ██║   ╚██████╔╝╚██████╔╝███████╗███████║
  ╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝          ╚═╝    ╚═════╝  ╚═════╝ ╚══════╝╚══════╝

Feature: rust_tools | File: zsh/zsh.d/62-rust.zsh | Status: rusttools

Commands

Alias Description
cb cargo build
cbr cargo build --release
ct cargo test
ctr cargo test --release
cr cargo run
crr cargo run --release
ccl cargo clippy
cf cargo fmt
cfc cargo fmt --check
cw cargo watch (requires cargo-watch)
cwt cargo watch -x test
cwr cargo watch -x run
cwc cargo watch -x check
cdoc cargo doc --open
cu cargo update
cadd cargo add
crm cargo rm

Features

  • Watch mode integration: cw* aliases for TDD workflow
  • Clippy by default: Lint-first development
  • Format checking: cfc for CI-friendly format checks
  • cargo-edit integration: cadd/crm for dependency management

Example Workflow

# Start TDD cycle
cwt                          # Watch and run tests on save

# In another terminal, check lints
ccl

# Format before commit
cf

# Build release
cbr

# Generate and view docs
cdoc

Go Tools

   ██████╗  ██████╗     ████████╗ ██████╗  ██████╗ ██╗     ███████╗
  ██╔════╝ ██╔═══██╗    ╚══██╔══╝██╔═══██╗██╔═══██╗██║     ██╔════╝
  ██║  ███╗██║   ██║       ██║   ██║   ██║██║   ██║██║     ███████╗
  ██║   ██║██║   ██║       ██║   ██║   ██║██║   ██║██║     ╚════██║
  ╚██████╔╝╚██████╔╝       ██║   ╚██████╔╝╚██████╔╝███████╗███████║
   ╚═════╝  ╚═════╝        ╚═╝    ╚═════╝  ╚═════╝ ╚══════╝╚══════╝

Feature: go_tools | File: zsh/zsh.d/63-go.zsh | Status: gotools

Commands

Alias Description
gob go build
gobr go build for current OS/arch
got go test ./...
gotv go test -v ./...
gotc go test -cover ./...
gocover Generate and open HTML coverage report
gor go run .
gom go mod
gomt go mod tidy
gomi go mod init
goget go get
gofmt gofmt -w .
goimports Run goimports on project
golint Run golangci-lint
govet go vet ./...
godoc Start local godoc server

Features

  • Coverage workflow: gocover generates HTML report and opens browser
  • Module management: gom* aliases for common mod operations
  • Linting integration: golint runs golangci-lint if installed
  • Local docs: godoc starts documentation server

Example Workflow

# Initialize new module
gomi github.com/user/myproject

# Run tests with coverage
gotc

# Generate coverage report
gocover                      # Opens browser with coverage HTML

# Tidy dependencies
gomt

# Lint before commit
golint
govet

Python Tools

  ██████╗ ██╗   ██╗████████╗██╗  ██╗ ██████╗ ███╗   ██╗    ████████╗ ██████╗  ██████╗ ██╗     ███████╗
  ██╔══██╗╚██╗ ██╔╝╚══██╔══╝██║  ██║██╔═══██╗████╗  ██║    ╚══██╔══╝██╔═══██╗██╔═══██╗██║     ██╔════╝
  ██████╔╝ ╚████╔╝    ██║   ███████║██║   ██║██╔██╗ ██║       ██║   ██║   ██║██║   ██║██║     ███████╗
  ██╔═══╝   ╚██╔╝     ██║   ██╔══██║██║   ██║██║╚██╗██║       ██║   ██║   ██║██║   ██║██║     ╚════██║
  ██║        ██║      ██║   ██║  ██║╚██████╔╝██║ ╚████║       ██║   ╚██████╔╝╚██████╔╝███████╗███████║
  ╚═╝        ╚═╝      ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝       ╚═╝    ╚═════╝  ╚═════╝ ╚══════╝╚══════╝
  Powered by uv

Feature: python_tools | File: zsh/zsh.d/64-python.zsh | Status: pythontools

Python development powered by uv—a fast Python package manager that handles:

  • Package management (replacing pip, pip-tools)
  • Virtual environments (replacing venv)
  • Python version management (replacing pyenv)

uv Aliases

Alias Description
uvs uv sync - Sync from lock file
uvr uv run - Run in project environment
uva uv add - Add dependency
uvad uv add --dev - Add dev dependency
uvrm uv remove - Remove dependency
uvl uv lock - Update lock file
uvu uv lock --upgrade - Upgrade all
uvt uv tree - Show dependency tree
uvv uv venv - Create virtual environment
uvpyl uv python list - List Python versions
uvpyi uv python install - Install Python version

Pytest Aliases

Alias Description
pt pytest
ptv pytest -v - Verbose
ptx pytest -x - Stop on first failure
ptxv pytest -xvs - Verbose, stop, show output
ptc pytest --cov - With coverage
ptl pytest --last-failed - Only last failed
pts pytest -s - Show print statements
ptk pytest -k - Match expression

Auto-venv Activation

Automatically prompts to activate virtual environments when entering directories:

cd my-project/
# 󰌠 Virtual environment detected: .venv
# Activate? [Y/n]

Configuration:

export PYTHON_AUTO_VENV="notify"  # Prompt (default)
export PYTHON_AUTO_VENV="auto"    # Auto-activate
export PYTHON_AUTO_VENV="off"     # Disable

Helper Functions

Function Description
uv-new <name> Create new project (app/lib/script)
uv-clean Remove Python artifacts (pycache, etc.)
uv-info Show Python/uv environment info
uv-python-setup <ver> Install and pin Python version
pt-watch Run pytest in watch mode
pt-cov Coverage with HTML report

Example Workflow

# Create new project
uv-new my-api app
cd my-api

# Add dependencies
uva fastapi uvicorn
uvad pytest pytest-cov

# Sync and run
uvs
uvr python -m uvicorn main:app --reload

# Run tests
ptxv                 # Stop on first failure, verbose
pt-cov               # Coverage with HTML report

SSH Tools

  ███████╗███████╗██╗  ██╗    ████████╗ ██████╗  ██████╗ ██╗     ███████╗
  ██╔════╝██╔════╝██║  ██║    ╚══██╔══╝██╔═══██╗██╔═══██╗██║     ██╔════╝
  ███████╗███████╗███████║       ██║   ██║   ██║██║   ██║██║     ███████╗
  ╚════██║╚════██║██╔══██║       ██║   ██║   ██║██║   ██║██║     ╚════██║
  ███████║███████║██║  ██║       ██║   ╚██████╔╝╚██████╔╝███████╗███████║
  ╚══════╝╚══════╝╚═╝  ╚═╝       ╚═╝    ╚═════╝  ╚═════╝ ╚══════╝╚══════╝

Feature: ssh_tools | File: zsh/zsh.d/65-ssh.zsh | Status: sshtools

SSH Config Management

Command Description
sshlist / sshtools hosts List all hosts from ~/.ssh/config (styled table)
sshgo <host> Quick connect with completion
sshedit Open SSH config in $EDITOR
sshadd-host <name> Interactive wizard to add new host
sshtools remove-host <name> Remove host from SSH config

SSH Key Management

Command Description
sshkeys List all keys with fingerprints
sshgen <name> Generate new ED25519 key
sshcopy <host> Copy public key to remote host
sshfp [key] Show fingerprint(s) (SHA256/MD5)

SSH Agent Commands

Command Description
sshagent Start agent / show loaded keys
sshload [key] Add key to agent
sshunload <key> Remove key from agent
sshclear Remove all keys from agent

SSH Tunnel Helpers

Command Description
sshtunnel <host> <local> [remote] Create port forward
sshsocks <host> [port] SOCKS5 proxy (default: 1080)
sshtunnels List active SSH connections

Features

  • Agent detection: Logo color indicates agent status (green=running, yellow=no keys, red=stopped)
  • Styled tables: keys, hosts, and agent commands display output in colored box-drawing tables
  • Tab completions: sshgo <TAB> completes from configured hosts
  • Key name resolution: Commands find keys by name (sshload github finds id_ed25519_github)
  • Interactive host setup: sshadd-host guides through adding new SSH hosts
  • Host removal: sshtools remove-host <name> cleanly removes a host block from config

Example Workflow

# Start of day: check agent status (styled table output)
sshtools agent

# Load your work keys
sshload github
sshload work-server

# Quick connect to a host
sshgo prod-server

# Create a tunnel for database access
sshtunnel db-server 5432

# List what's configured (styled table with HostName, User, Port, IdentityFile)
sshtools hosts

# Generate a new key for a project
sshgen client-project "Client Project Deploy Key"

# Manage hosts
sshtools add-host staging --hostname 10.0.0.5 --user deploy
sshtools remove-host old-server

Docker Tools

  ██████╗  ██████╗  ██████╗██╗  ██╗███████╗██████╗     ████████╗ ██████╗  ██████╗ ██╗     ███████╗
  ██╔══██╗██╔═══██╗██╔════╝██║ ██╔╝██╔════╝██╔══██╗    ╚══██╔══╝██╔═══██╗██╔═══██╗██║     ██╔════╝
  ██║  ██║██║   ██║██║     █████╔╝ █████╗  ██████╔╝       ██║   ██║   ██║██║   ██║██║     ███████╗
  ██║  ██║██║   ██║██║     ██╔═██╗ ██╔══╝  ██╔══██╗       ██║   ██║   ██║██║   ██║██║     ╚════██║
  ██████╔╝╚██████╔╝╚██████╗██║  ██╗███████╗██║  ██║       ██║   ╚██████╔╝╚██████╔╝███████╗███████║
  ╚═════╝  ╚═════╝  ╚═════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝       ╚═╝    ╚═════╝  ╚═════╝ ╚══════╝╚══════╝

Feature: docker_tools | File: zsh/zsh.d/66-docker.zsh | Status: dockertools

Container Commands

Alias Description
dps docker ps
dpsa docker ps -a
di docker images
dsh <c> Shell into container (bash→sh fallback)
dex <c> [cmd] Execute command in container
dl / dlf docker logs / logs -f
dstop / dstart Stop / start container
drm / drmi Remove container / image

Docker Compose

Alias Description
dc docker compose
dcu / dcud compose up / up -d
dcd compose down
dcr compose restart
dcl compose logs -f
dcps compose ps
dcb compose build
dcex compose exec

Inspection & Networking

Command Description
dip <container> Get container IP address
denv <container> Show container env vars
dports Show all exposed ports
dstats Pretty docker stats
dvols List volumes
dnets List networks
dinspect <c> [jq] Inspect with jq filtering

Cleanup Commands

Command Description
dclean Remove stopped containers + dangling images
dprune Interactive system prune
dprune-all Aggressive cleanup (with confirmation)

Features

  • Daemon detection: Logo color indicates Docker status (green=running with containers, cyan=running, red=stopped)
  • Tab completions: Container names auto-complete
  • jq integration: dinspect myapp .NetworkSettings for filtered inspection
  • Compose v2: All compose commands use docker compose (v2)

Example Workflow

# Check what's running
dps
dockertools              # Full status dashboard

# Start a compose project
dcud                     # docker compose up -d
dcl                      # Follow logs

# Debug a container
dsh webapp              # Shell into container
denv webapp             # Check environment
dip webapp              # Get IP address

# Inspect with filtering
dinspect webapp .NetworkSettings.Networks

# Cleanup
dclean                  # Quick cleanup
dprune                  # Interactive prune

NVM (Node.js)

Feature: nvm_integration File: zsh/zsh.d/90-integrations.zsh

Lazy Loading

NVM is lazy-loaded for fast shell startup. It initializes on first use of:

  • node
  • npm
  • npx
  • nvm
  • yarn
  • pnpm

Commands

Standard NVM commands, plus:

Command Description
nvm use Switch Node version
nvm install Install Node version
nvm ls List installed versions
nvm current Show current version

Auto-switching

If .nvmrc exists in a directory, NVM automatically switches versions when you cd into it.

# Project with .nvmrc
cd my-project/
# Found '.nvmrc' with version <18>
# Now using node v18.19.0

node --version
# v18.19.0

SDKMAN (Java)

Feature: sdkman_integration File: zsh/zsh.d/90-integrations.zsh

Lazy Loading

SDKMAN is lazy-loaded for fast shell startup. It initializes on first use of:

  • java
  • javac
  • gradle
  • mvn
  • kotlin
  • sdk

Commands

Standard SDKMAN commands:

Command Description
sdk list java List available Java versions
sdk install java 21-tem Install Temurin Java 21
sdk use java 17-tem Switch to Java 17
sdk current Show current versions
sdk default java 21-tem Set default Java version

Supported Tools

SDKMAN manages:

  • Java (multiple distributions: Temurin, Corretto, GraalVM, etc.)
  • Gradle
  • Maven
  • Kotlin
  • Scala
  • Groovy
  • And 50+ other JVM tools

Shell Completions

All tool commands have tab completion:

# AWS
awsswitch <TAB>              # Shows profile names

# blackdot
blackdot <TAB>               # Shows subcommands
blackdot features <TAB>      # Shows: enable disable list preset status
blackdot features enable <TAB>  # Shows: vault aws_helpers rust_tools ...

# Rust
cargo <TAB>                  # Standard cargo completions

# Go
go <TAB>                     # Standard go completions

Completions are loaded from zsh/completions/ directory.

Discoverability

zsh-you-should-use

The zsh-you-should-use plugin reminds you about aliases you're not using:

$ cargo build
# Found existing alias for "cargo build". You should use: "cb"

$ go test ./...
# Found existing alias for "go test ./...". You should use: "got"

Over time, this trains muscle memory for the shortcuts.

Adding Custom Aliases

Add your own aliases in ~/.config/blackdot/aliases.local.zsh:

# My custom aliases
alias mytest='cargo test --workspace --all-features'
alias mydeploy='cdk deploy --require-approval never'

This file is sourced after the standard aliases, so you can override defaults.

Related Documentation