---
title: "CLI: Guides & Troubleshooting — WindKeep"
description: "Guides and troubleshooting for the WindKeep CLI."
canonical_url: "https://windkeep.up.railway.app/cli-guide/guides"
meta:
  "og:description": "Guides and troubleshooting for the WindKeep CLI."
  "og:image": "https://windkeep.up.railway.app/og-image.png"
  "og:title": "CLI: Guides & Troubleshooting — WindKeep"
---

> Index of every page on this site: [llms.txt](https://windkeep.up.railway.app/llms.txt)

# 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.

Use a **service token** (`st_…`) from the project's Access Control tab — not a personal API token. Service tokens are scoped to one project and selected environments, so a leaked CI secret cannot list orgs or delete resources.

Set `WINDKEEP_TOKEN` and `WINDKEEP_PROJECT_ID` as CI secrets. The CLI reads them from the environment — no `login` or `projects switch` step is required.

*Personal tokens from Preferences still work for interactive CLI use. Prefer service tokens anywhere credentials live in CI.*

**GitHub Actions:**

```
- name: Deploy with WindKeep secrets
  env:
    WINDKEEP_TOKEN: ${{ secrets.WINDKEEP_TOKEN }}
    WINDKEEP_PROJECT_ID: ${{ secrets.WINDKEEP_PROJECT_ID }}
  run: windkeep run --env prod npm run build
```

**GitLab CI:**

```
deploy:
  stage: deploy
  variables:
    WINDKEEP_TOKEN: $WINDKEEP_TOKEN
    WINDKEEP_PROJECT_ID: $WINDKEEP_PROJECT_ID
  script:
    - windkeep run --env prod npm run deploy
```

**Optional — persist a service token locally:**

```
# Validates st_… against /api/service-token and pins the scoped project
windkeep login st_your_service_token
windkeep whoami
windkeep run --env prod npm run build
```

## 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. Org owners retain break-glass access to all projects.
- **Verify safely:** Use -v/--verbose to confirm which keys are injected — values are never printed.

```json
{"@context":"https://schema.org","@graph":[{"@id":"https://windkeep.up.railway.app/#website","@type":"WebSite","name":"WindKeep","url":"https://windkeep.up.railway.app/"},{"@id":"https://windkeep.up.railway.app/cli-guide/guides#webpage","@type":"WebPage","description":"Guides and troubleshooting for the WindKeep CLI.","name":"CLI: Guides & Troubleshooting","url":"https://windkeep.up.railway.app/cli-guide/guides","isPartOf":{"@id":"https://windkeep.up.railway.app/#website"},"potentialAction":[{"@type":"ReadAction","target":["https://windkeep.up.railway.app/cli-guide/guides"]}]}]}
```

## Sitemap

See the full [sitemap](https://windkeep.up.railway.app/sitemap.md) for all pages.
