CLI: Guides & Troubleshooting

Workflow: New Project Setup

Scenario: You are starting a new application and want WindKeep to manage all secrets from day one.

# Create your organization and project
windkeep orgs create "My Company"
windkeep projects create "Backend API" -d "Main backend service"

# Add secrets for each environment
windkeep secrets create DATABASE_URL \
  --description "PostgreSQL connection" \
  --dev "postgres://localhost:5432/myapp_dev" \
  --staging "postgres://staging-db:5432/myapp" \
  --prod "postgres://prod-db:5432/myapp"

windkeep secrets create STRIPE_KEY \
  --description "Stripe API key" \
  --dev "sk_test_abc123" \
  --prod "sk_live_xyz789"

# Verify secrets and start your app
windkeep secrets list
windkeep run npm run dev

Workflow: Migrating from .env Files

Scenario: You have existing .env files and want to move secrets into WindKeep without rewriting your workflow overnight.

# 1. Review keys in your local .env files (DATABASE_URL, API_KEY, etc.)

# 2. Switch to the target project and create secrets
windkeep projects switch my-app
windkeep secrets create DATABASE_URL --dev "postgres://localhost:5432/dev"

# 3. Add staging and production values
windkeep secrets set DATABASE_URL --prod "postgres://prod-db:5432/app"

# 4. Verify injection works, then remove local files
windkeep run npm run dev
rm .env.development .env.production

# Alternative: bulk import from an existing .env file
windkeep push .env --overwrite

Workflow: Cross-Org Context Switching

Scenario: You work across personal and client organizations and need to switch contexts without mixing secrets.

# Switch org and project, then run your app
windkeep orgs switch cm123personal
windkeep projects switch personal-blog
windkeep run npm run dev

# Create shell aliases for frequent context switches
alias dev-backend='windkeep orgs switch cm123 && windkeep projects switch backend && windkeep run npm run dev'

# Or override the project for a one-off command
windkeep run -p other-project npm run task

Workflow: CI/CD Pipeline Integration

Scenario: You want to inject secrets in GitHub Actions or GitLab CI without committing static config files.

GitHub Actions:

- name: Deploy with WindKeep secrets
  env:
    WINDKEEP_TOKEN: ${{ secrets.WINDKEEP_TOKEN }}
  run: |
    windkeep login $WINDKEEP_TOKEN
    windkeep projects switch my-app
    windkeep run --env prod npm run build

GitLab CI:

deploy:
  stage: deploy
  script:
    - windkeep login $WINDKEEP_TOKEN
    - windkeep projects switch my-app
    - windkeep run --env prod npm run deploy

Workflow: Managing Microservices

Scenario: You run multiple services locally, each with its own project and secret set.

# Terminal 1 — Auth service
windkeep projects switch auth-service && windkeep run npm run dev

# Terminal 2 — API gateway
windkeep projects switch api-gateway && windkeep run npm run dev

# Terminal 3 — Payment service
windkeep projects switch payment-service && windkeep run npm run dev

Benefits

Centralizing secrets in WindKeep reduces several common risks:

windkeep run -e staging npm test
  • Zero disk drift: No .env files to accidentally commit to version control.
  • Single source of truth: Rotate keys in one place — CI/CD picks up changes on the next run.
  • Fast onboarding: New developers log in, switch to the right project, and run immediately.
  • Reliable testing: Run staging tests against real secrets, not stale local files.

Troubleshooting: Authentication & Context

# Config file not found — you are not logged in
windkeep login YOUR_API_TOKEN

# Token expired or invalid — re-authenticate
windkeep logout
windkeep login YOUR_API_TOKEN

# No active organization or project — set your context
windkeep orgs list
windkeep orgs switch ORG_ID
windkeep projects list
windkeep projects switch PROJECT_SLUG

Troubleshooting: Missing Runtime Variables

If windkeep run starts your process but environment variables are empty, work through these checks:

# Wrong environment? Defaults to development
windkeep run -v -e prod npm start

# Wrong project? Check context or override
windkeep whoami
windkeep run -p target-project-slug npm start

# Missing value? Confirm the secret exists and has a value for that env
windkeep secrets get DATABASE_URL

Security & Collaboration

A few practices that keep secrets safe across teams:

  • Never log decrypted values: Keep secrets out of logs, error reports, and metrics.
  • Least privilege: Assign OWNER, ADMIN, and MEMBER roles based on what each person actually needs.
  • Verify safely: Use -v/--verbose to confirm which keys are injected — values are never printed.