Managing Credentials

Manage your iOS and Android build credentials locally for convenient cloud builds.

Overview

Capgo CLI allows you to save build credentials locally on your machine in ~/.capgo/credentials.json. When you run a build, these credentials are automatically used and sent securely to Capgo’s build servers.

Security Guarantee

Your credentials are NEVER stored permanently on Capgo servers:

• ✅ Used ONLY during the active build process
• ✅ Automatically deleted after build completion
• ✅ Maximum retention: 24 hours (even if build fails)
• ✅ Apps are sent directly to App Store/Play Store - we store NOTHING
• ✅ Transmitted securely over HTTPS

Commands

Save Credentials

Store your build credentials locally for automatic use:

npx @capgo/cli build credentials save --platform <ios|android> [options]

List Credentials

View currently saved credentials (passwords are masked):

npx @capgo/cli build credentials list

Clear Credentials

Remove saved credentials from your local machine:

# Clear all credentials
npx @capgo/cli build credentials clear

# Clear only iOS credentials
npx @capgo/cli build credentials clear --platform ios

# Clear only Android credentials
npx @capgo/cli build credentials clear --platform android

Saving iOS Credentials

Complete Example

npx @capgo/cli build credentials save \
  --platform ios \
  --certificate ./cert.p12 \
  --p12-password "YourP12Password" \
  --provisioning-profile ./profile.mobileprovision \
  --apple-key ./AuthKey_ABC1234567.p8 \
  --apple-key-id "ABC1234567" \
  --apple-issuer-id "00000000-0000-0000-0000-000000000000" \
  --apple-team-id "TEAM123456"

iOS Options

Option	Description	Required
--certificate <path>	Path to .p12 certificate file	Yes (release)
--p12-password <password>	Password for the .p12 certificate	Yes (release)
--provisioning-profile <path>	Path to .mobileprovision file	Yes (release)
--provisioning-profile-prod <path>	Production provisioning profile (optional)	No
--apple-key <path>	Path to App Store Connect API .p8 key	Yes (submission)
--apple-key-id <id>	App Store Connect API Key ID	Yes (submission)
--apple-issuer-id <id>	App Store Connect API Issuer ID (UUID)	Yes (submission)
--apple-team-id <id>	App Store Connect Team ID	Yes (submission)
--apple-id <email>	Apple ID email (alternative auth)	No
--apple-app-password <password>	App-specific password (alternative auth)	No

What Gets Stored

When you save iOS credentials, the CLI:

1. Reads the certificate and provisioning profile files
2. Converts them to base64 encoding
3. Saves the base64 strings to ~/.capgo/credentials.json
4. Stores passwords and IDs as plain text (local file only)

The stored file structure:

{
  "ios": {
    "BUILD_CERTIFICATE_BASE64": "...",
    "BUILD_PROVISION_PROFILE_BASE64": "...",
    "APPLE_KEY_CONTENT": "...",
    "P12_PASSWORD": "...",
    "APPLE_KEY_ID": "ABC1234567",
    "APPLE_ISSUER_ID": "...",
    "APP_STORE_CONNECT_TEAM_ID": "TEAM123456"
  }
}

Saving Android Credentials

Complete Example

npx @capgo/cli build credentials save \
  --platform android \
  --keystore ./release.keystore \
  --keystore-alias "my-key-alias" \
  --keystore-key-password "KeyPassword123" \
  --keystore-store-password "StorePassword123" \
  --play-config ./play-store-service-account.json

Android Options

Option	Description	Required
--keystore <path>	Path to .keystore or .jks file	Yes (release)
--keystore-alias <alias>	Key alias in the keystore	Yes (release)
--keystore-key-password <password>	Password for the key alias	Yes (release)
--keystore-store-password <password>	Password for the keystore	Yes (release)
--play-config <path>	Path to Play Store service account JSON	Yes (submission)

What Gets Stored

When you save Android credentials, the CLI:

1. Reads the keystore and service account JSON files
2. Converts them to base64 encoding
3. Saves the base64 strings to ~/.capgo/credentials.json
4. Stores passwords and alias as plain text (local file only)

The stored file structure:

{
  "android": {
    "ANDROID_KEYSTORE_FILE": "...",
    "PLAY_CONFIG_JSON": "...",
    "KEYSTORE_KEY_ALIAS": "my-key-alias",
    "KEYSTORE_KEY_PASSWORD": "...",
    "KEYSTORE_STORE_PASSWORD": "..."
  }
}
}

Using Saved Credentials

Once you’ve saved credentials, they’re automatically used when you build:

# Credentials automatically loaded from ~/.capgo/credentials.json
npx @capgo/cli build com.example.app --platform ios

You can also override saved credentials using environment variables:

# Environment variables take precedence over saved credentials
BUILD_CERTIFICATE_BASE64="..." \
P12_PASSWORD="different-password" \
npx @capgo/cli build com.example.app --platform ios

Precedence order:

1. Environment variables (highest priority)
2. Saved credentials in ~/.capgo/credentials.json
3. No credentials (lowest priority)

Viewing Saved Credentials

List what credentials you have saved:

npx @capgo/cli build credentials list

Example output:

📋 Saved Build Credentials:

iOS Credentials:
  ✓ Certificate (base64)
  ✓ Provisioning Profile (base64)
  ✓ Apple Key Content (base64)
  ✓ P12 Password: ********
  ✓ Apple Key ID: ABC1234567
  ✓ Apple Issuer ID: 00000000-0000-0000-0000-000000000000
  ✓ Team ID: TEAM123456

Android Credentials:
  ✓ Keystore (base64)
  ✓ Play Store Config (base64)
  ✓ Keystore Alias: my-key-alias
  ✓ Key Password: ********
  ✓ Store Password: ********

Location: ~/.capgo/credentials.json

🔒 These credentials are stored locally on your machine only.
   When building, they are sent to Capgo but NEVER stored there.
   They are auto-deleted after build completion (max 24 hours).

Security Best Practices

Local Storage Security

1. File Permissions

   # Ensure credentials file is not readable by others
   chmod 600 ~/.capgo/credentials.json

2. Never Commit Credentials

   # Add to .gitignore
   echo ".capgo/" >> .gitignore

3. Separate Credentials

   • Use different credentials for local development vs CI/CD
   • Rotate credentials regularly
   • Don’t share credentials between team members

CI/CD Usage

For CI/CD environments, prefer environment variables over saved credentials:

# GitHub Actions
env:
  BUILD_CERTIFICATE_BASE64: ${{ secrets.IOS_CERTIFICATE }}
  P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
  # ... other secrets

This is more secure because:

• Secrets are managed by your CI/CD platform
• No credential files on runners
• Easy rotation and access control
• Audit trails for secret usage

Credential Rotation

Regularly rotate your credentials:

1. iOS: Generate new certificates and API keys yearly
2. Android: Change keystore passwords annually
3. After team changes: Rotate when team members leave

Update saved credentials:

# Re-run save command with new credentials
npx @capgo/cli build credentials save --platform ios --certificate ./new-cert.p12 ...

Troubleshooting

”No credentials found”

If the build says no credentials were found:

1. Check if credentials are saved:

   npx @capgo/cli build credentials list

2. Save credentials if missing:

   npx @capgo/cli build credentials save --platform ios ...

3. Verify file exists:

   cat ~/.capgo/credentials.json

“Permission denied” when reading credentials

Fix file permissions:

chmod 600 ~/.capgo/credentials.json

Credentials not being used

Check that the correct platform is specified:

# Make sure --platform matches saved credentials
npx @capgo/cli build com.example.app --platform ios  # Uses ios credentials
npx @capgo/cli build com.example.app --platform android  # Uses android credentials

Clear and re-save credentials

If credentials seem corrupted:

# Clear all credentials
npx @capgo/cli build credentials clear

# Save again
npx @capgo/cli build credentials save --platform ios ...

Migration from Environment Variables

If you’re currently using environment variables, you can migrate to saved credentials:

1. Extract your current environment variables

   echo $BUILD_CERTIFICATE_BASE64  # Verify they exist

2. Decode base64 files back to original files (if needed)

   echo "$BUILD_CERTIFICATE_BASE64" | base64 -d > cert.p12
   echo "$BUILD_PROVISION_PROFILE_BASE64" | base64 -d > profile.mobileprovision

3. Save using the CLI

   npx @capgo/cli build credentials save \
     --platform ios \
     --certificate ./cert.p12 \
     --provisioning-profile ./profile.mobileprovision \
     --p12-password "$P12_PASSWORD" \
     --apple-key-id "$APPLE_KEY_ID" \
     --apple-issuer-id "$APPLE_ISSUER_ID" \
     --apple-team-id "$APP_STORE_CONNECT_TEAM_ID"

4. Test the build

   npx @capgo/cli build com.example.app --platform ios

5. Remove environment variables (optional)

   unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64

File Location

Credentials are stored at:

• macOS/Linux: ~/.capgo/credentials.json
• Windows: %USERPROFILE%\.capgo\credentials.json

The file is automatically created when you save credentials for the first time.

Next Steps

• Getting Started - Create your first build
• iOS Builds - iOS-specific build configuration
• Android Builds - Android-specific build configuration
• Troubleshooting - Common issues and solutions

Need Help?

• 📚 Troubleshooting guide
• 💬 Discord community
• 📧 Email: support@capgo.app