terrylica Doppler Credential Workflows
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
When to Use This Skill
Use this skill when:
- Publishing Python packages to PyPI
- Rotating AWS access keys
- Managing credentials across multiple services
- Troubleshooting authentication failures (403, InvalidClientTokenId)
- Setting up Doppler credential injection patterns
- Multi-token/multi-account strategies
Quick Reference
Core Pattern: Doppler CLI
Standard Usage:
doppler run --project <project> --config <config> --command='<command>'
Why --command flag:
- Official Doppler pattern (auto-detects shell)
- Ensures variables expand AFTER Doppler injects them
- Without it: shell expands
$VARbefore Doppler runs → empty string
Quick Start Examples
PyPI Publishing
doppler run --project claude-config --config dev \
--command='uv publish --token "$PYPI_TOKEN"'
AWS Operations
doppler run --project aws-credentials --config dev \
--command='aws s3 ls --region $AWS_DEFAULT_REGION'
Best Practices
- Always use --command flag for credential injection
- Use project-scoped tokens (PyPI) for better security
- Rotate credentials regularly (90 days recommended)
- Document with Doppler notes:
doppler secrets notes set <SECRET> "<note>" - Use stdin for storing secrets:
echo -n 'secret' | doppler secrets set - Test injection before using:
echo ${#VAR}to verify length - Multi-token naming:
SERVICE_TOKEN_{ABBREV}for clarity
Reference Documentation
For detailed information, see:
- PyPI Publishing - Token setup, publishing, troubleshooting
- AWS Credentials - Rotation workflow, setup, troubleshooting
- Multi-Service Patterns - Multiple PyPI packages, multiple AWS accounts
- AWS Workflow - Complete AWS credential management guide
Bundled Specifications:
PYPI_REFERENCE.yaml- Complete PyPI specAWS_SPECIFICATION.yaml- AWS credential architecture
Using mise [env] for Local Development (Recommended)
For local development, mise [env] provides a simpler alternative to doppler run:
# .mise.toml
[env]
# Fetch from Doppler with caching for performance
PYPI_TOKEN = "{{ cache(key='pypi_token', duration='1h', run='doppler secrets get PYPI_TOKEN --project claude-config --config prd --plain') }}"
Do NOT use mise
[env]for GitHub tokens (ADR 2026-06-21). GitHub multi-account auth is driven by the repo'soriginhost-alias (git@github.com-<account>:…), not mise. A token resolves fresh per-repo via~/.claude/tools/bin/gh-token-for-repo; an ambientGH_TOKENoutranks the isolated gh profile and 401s after a rotation. The.secrets/gh-token-*files are deleted.
When to use mise [env] (for non-GitHub secrets like PYPI_TOKEN):
- Per-directory credential configuration
- Credentials that persist across commands (not session-scoped)
When to use doppler run:
- CI/CD pipelines
- Single-command credential scope
- When you want credentials auto-cleared after command
See mise-configuration skill for complete patterns.
PyPI Publishing Policy
For PyPI publishing, see pypi-doppler skill for LOCAL-ONLY workspace policy.
Do NOT configure PyPI publishing in GitHub Actions or CI/CD pipelines.
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| 403 on PyPI publish | Token expired or wrong scope | Regenerate project-scoped token, update in Doppler |
| InvalidClientTokenId (AWS) | Access key rotated or deleted | Run AWS key rotation workflow, update Doppler |
| Variable expands empty | Using $VAR without --command |
Always use --command='...$VAR...' pattern |
| Doppler CLI not found | Not installed | brew install dopplerhq/cli/doppler |
| Wrong config selected | Ambiguous project/config | Specify both --project and --config explicitly |
| mise [env] not loading | Not in directory with .mise.toml | cd to project directory or check mise.toml path |
| Secret retrieval slow | No caching configured | Use mise cache() with duration for repeated access |
| Token length mismatch | Copied with extra whitespace | Trim token: echo -n 'secret' | doppler secrets set |
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.