Skip to main content

Documentation Index

Fetch the complete documentation index at: https://superflag.sh/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
CI/CD Integration

Use the Superflag CLI in your continuous integration and deployment workflows to automate flag management.
This guide covers production CI/CD usage. For AI-assisted development, see the Claude Code skill.

​
Authentication in CI

For CI/CD environments, you’ll need to obtain a CLI token and store it as a secret.

​
Step 1: Get CLI Token

On your local machine: 
superflag login
cat ~/.superflag/credentials.json
Copy the token value (starts with cli_).

​
Step 2: Store as Secret

Store the token in your CI platform’s secrets:
  1. Go to repository Settings → Secrets and variables → Actions
  2. Create new secret: SUPERFLAG_TOKEN
  3. Paste your token

​
Step 3: Set Token in CI

Create the credentials file in your CI workflow: 
mkdir -p ~/.superflag
echo "{\"token\":\"$SUPERFLAG_TOKEN\"}" > ~/.superflag/credentials.json

​
CI/CD Examples

​
GitHub Actions

.github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Superflag CLI
        run: |
          npm install -g @superflag-sh/cli
          mkdir -p ~/.superflag
          echo "{\"token\":\"${{ secrets.SUPERFLAG_TOKEN }}\"}" > ~/.superflag/credentials.json

      - name: Update production flags
        run: |
          superflag use my-app production
          superflag set deployment-version ${{ github.sha }}
          superflag set deployed-at $(date -u +%Y-%m-%dT%H:%M:%SZ)

      - name: Deploy
        run: npm run deploy

​
GitLab CI

.gitlab-ci.yml
deploy:
  stage: deploy
  only:
    - main
  before_script:
    - npm install -g @superflag-sh/cli
    - mkdir -p ~/.superflag
    - echo "{\"token\":\"$SUPERFLAG_TOKEN\"}" > ~/.superflag/credentials.json
  script:
    - superflag use my-app production
    - superflag set deployment-version $CI_COMMIT_SHA
    - superflag set deployed-at $(date -u +%Y-%m-%dT%H:%M:%SZ)
    - npm run deploy

​
CircleCI

.circleci/config.yml
version: 2.1

jobs:
  deploy:
    docker:
      - image: cimg/node:18.0
    steps:
      - checkout

      - run:
          name: Install Superflag CLI
          command: |
            npm install -g @superflag-sh/cli
            mkdir -p ~/.superflag
            echo "{\"token\":\"$SUPERFLAG_TOKEN\"}" > ~/.superflag/credentials.json

      - run:
          name: Update flags
          command: |
            superflag use my-app production
            superflag set deployment-version $CIRCLE_SHA1

      - run:
          name: Deploy
          command: npm run deploy

workflows:
  version: 2
  deploy:
    jobs:
      - deploy:
          filters:
            branches:
              only: main

​
Common Patterns

​
Feature Flag Deployment

Enable a feature flag after successful deployment: 
- name: Deploy application
  run: npm run deploy

- name: Enable new feature
  run: |
    superflag use my-app production
    superflag set new-feature true

​
Environment-Specific Configuration

# Staging deployment
if [ "$CI_BRANCH" = "develop" ]; then
  superflag use my-app staging
  superflag set api-url https://api-staging.example.com
fi

# Production deployment
if [ "$CI_BRANCH" = "main" ]; then
  superflag use my-app production
  superflag set api-url https://api.example.com
fi

​
Bulk Flag Updates

- name: Update all flags for release
  run: |
    cat > flags.json <<EOF
    {
      "new-ui": true,
      "old-ui": false,
      "api-version": "v2",
      "maintenance-mode": false
    }
    EOF
    superflag use my-app production
    superflag flags bulk-set --file flags.json

​
Rollback on Failure

- name: Deploy
  id: deploy
  run: npm run deploy

- name: Rollback flags on failure
  if: failure()
  run: |
    superflag use my-app production
    superflag set new-feature false
    superflag set api-version v1

​
Best Practices

​
1. Use Context

Set context once per job to avoid repeating --app and --env: 
# ✅ Good
superflag use my-app production
superflag set feature-a true
superflag set feature-b false

# ❌ Verbose
superflag flags set --app my-app --env production --key feature-a --value true
superflag flags set --app my-app --env production --key feature-b --value false

​
2. Fail Fast

Check authentication before running other steps: 
- name: Verify Superflag auth
  run: superflag whoami

​
3. Log Flag Changes

Keep an audit trail of flag changes: 
- name: Update flags
  run: |
    echo "Updating flags at $(date)"
    superflag set new-feature true | tee -a flag-changes.log

​
4. Use Exit Codes

Check command success in scripts: 
if superflag set new-feature true; then
  echo "Flag updated successfully"
else
  echo "Failed to update flag"
  exit 1
fi

​
5. Separate Deploy and Feature Enable

Deploy code first, enable features second: 
- name: Deploy code
  run: npm run deploy

# Wait for deployment to stabilize
- name: Wait
  run: sleep 30

- name: Enable feature
  run: superflag set new-feature true

​
Security

​
Protect Your Token

  • Never commit ~/.superflag/credentials.json to version control
  • Store tokens in CI secrets, not in code
  • Use masked/protected variables in your CI platform
  • Rotate tokens if compromised

​
Audit Trail

All flag changes made via CLI are logged in your Superflag dashboard under “Activity”.

​
Troubleshooting

​
Authentication Fails

Error: Not authenticated
Solution: Verify your CI secret is set correctly: 
# Debug (remove after testing)
echo "Token length: ${#SUPERFLAG_TOKEN}"

​
Context Not Persisting

The use command saves context to ~/.superflag/context.json. Ensure this persists between steps: 
# Cache context between steps
- name: Set context
  run: superflag use my-app production

- name: Use context
  run: superflag get feature-flag

​
Commands Timeout

Network issues in CI can cause timeouts. Add retry logic: 
for i in {1..3}; do
  superflag set feature-flag true && break
  echo "Retry $i/3"
  sleep 5
done

​
Next Steps

Commands Reference

Complete command documentation

API Reference

Use the HTTP API directly