SuperPush CLI

A command-line interface for SuperPe CodePush - enabling over-the-air (OTA) updates for React Native applications.

Description

SuperPush CLI is a TypeScript-based tool that allows developers to build, release, and manage React Native app bundles for CodePush deployments. It provides seamless integration with the SuperPe CodePush service for delivering instant updates to mobile applications without going through app store approval processes.

Features

• 🚀 Easy Setup - Initialize your app with a simple command
• 📦 Bundle Building - Build optimized bundles for Android and iOS
• 🔄 OTA Releases - Deploy updates instantly to your users
• 📊 Release History - Interactive history viewer for all releases
• ⏪ Rollback Support - Quickly revert to previous versions
• 🗜️ Bundle Compression - Automatic Brotli compression for smaller bundles
• 🔧 CLI Upgrades - Self-updating capabilities

Installation

Install SuperPush CLI globally using npm:

npm install -g superpush

Quick Start

1. Login to SuperPush

First, login with your SuperPush credentials:

superpush login

You'll be prompted to enter your email and password.

2. Initialize Your App

Navigate to your React Native project and initialize:

superpush init

This will:

• Prompt you for your app name
• Register your app with the SuperPe CodePush service

3. Build Your Bundle

Build a platform-specific bundle:

# For Android
superpush build android

# For iOS
superpush build ios

4. Release Your Update

Deploy your bundle to users:

# Basic release
superpush release android 1.0.1

# Release with options
superpush release android 1.0.1 -m "Bug fixes and improvements" -f -r 50

Commands

superpush --version or superpush -v

Display the current version of SuperPush CLI.

superpush --version
superpush -v

superpush login

Login to SuperPush with your credentials.

superpush login

What it does:

• Prompts for email and password
• Authenticates with SuperPush service
• Stores authentication tokens securely
• Handles automatic token refresh

superpush logout

Logout from SuperPush and clear stored credentials.

superpush logout

What it does:

• Clears stored authentication tokens
• Logs out from current SuperPush session
• Requires confirmation before logout

superpush init

Initialize your React Native app for CodePush.

superpush init

What it does:

• Registers your app with SuperPe CodePush service
• Provides instructions for ignoring config from version control

superpush build [platform]

Build a React Native bundle for the specified platform, or both platforms if no platform is specified.

superpush build android   # Build for Android only
superpush build ios       # Build for iOS only
superpush build           # Build for both platforms

Arguments:

• platform - Optional target platform (android or ios). If not specified, builds for both platforms.

What it does:

• Runs react-native bundle command with optimized settings
• Outputs bundle to .superpush/<platform>/ directory
• Includes assets and creates production-ready bundle
• Can build for both platforms simultaneously when no platform is specified

superpush release <platform> <version> [options]

Release a bundle to your users via CodePush.

superpush release android 1.0.1
superpush release ios 1.0.2 -m "Critical bug fix" -f -r 25 -d

Arguments:

• platform - Target platform (android or ios)
• version - Version number (e.g., 1.0.1)

Options:

• -m, --message <message> - Release notes/message
• -f, --force - Mark release as mandatory (forces immediate update)
• -r, --rollout <percentage> - Gradual rollout percentage (1-100)
• -d, --delete - Delete local bundle files after successful release

What it does:

• Compresses bundle using Brotli compression
• Uploads bundle to SuperPe CodePush service
• Optionally cleans up local build files

superpush rollback <platform> <version> <patch>

Rollback to a specific version and patch.

superpush rollback android 1.0.1 v2

Arguments:

• platform - Target platform (android or ios)
• version - Version to rollback to (e.g., 1.0.1)
• patch - Patch identifier (e.g., v2, v3)

superpush history <platform>

View interactive release history for a platform.

superpush history android
superpush history ios

Arguments:

• platform - Platform to view history for (android or ios)

Features:

• Interactive navigation through releases
• View release details, notes, and statistics
• See rollout percentages and mandatory status

superpush disable <platform> <version> <patch>

Disable a specific version and patch.

superpush disable android 1.0.1 v2

Arguments:

• platform - Target platform (android or ios)
• version - Version to rollback to (e.g., 1.0.1)
• patch - Patch identifier (e.g., v2, v3)

superpush upgrade [version]

Upgrade SuperPush CLI to latest or specific version.

superpush upgrade           # Upgrade to latest
superpush upgrade 0.1.5     # Upgrade to specific version

Arguments:

• version - Optional version to upgrade to (defaults to latest)

Configuration

Authentication

SuperPush CLI now uses secure credential storage instead of environment variables. After running superpush login, your authentication tokens are stored securely in your system's keychain.

• Tokens are automatically refreshed when expired
• No need to manually set environment variables
• Use superpush logout to clear stored credentials

Configuration

After running superpush init, your app configuration is stored securely using the system keychain instead of a local file:

• App name and ID are stored securely per project
• No sensitive files to add to .gitignore
• Configuration is automatically managed by the CLI

Important: Add .superpush/ to your .gitignore to avoid committing build artifacts:

echo "\n# superpush CLI\n.superpush" >> .gitignore

Workflow Example

Here's a typical workflow for releasing an update:

# 1. Make changes to your React Native app
# 2. Build the bundle
superpush build android

# 3. Test locally (optional)
# 4. Release with gradual rollout
superpush release android 1.2.3 -m "Performance improvements" -r 20

# 5. Monitor adoption and increase rollout
superpush release android 1.2.3 -r 50

# 6. Full rollout when confident
superpush release android 1.2.3 -r 100

# 7. If issues arise, rollback
superpush rollback android 1.2.2 v1

File Structure

After initialization and building, your project will have:

your-project/
├── .superpush/
│   ├── config.json          # App configuration
│   ├── android/             # Android bundles
│   │   ├── index.android.bundle
│   │   └── index.android.bundle.br
│   └── ios/                 # iOS bundles
│       ├── main.jsbundle
│       └── main.jsbundle.br
└── ...

Requirements

• Node.js 16+
• React Native project
• Valid SuperPe CodePush session
• npm or yarn package manager

Troubleshooting

Common Issues

1. "SuperPush session not found"

   • Ensure you've logged in to superpush.

2. "Config file not found"

   • Run superpush init first to initialize your app

3. "Build failed"

   • Ensure you're in a valid React Native project directory
   • Check that all dependencies are installed (npm install)
   • Verify platform-specific setup is complete

4. "Release failed"

   • Ensure you've built the bundle first (superpush build <platform>)
   • Check your internet connection and API key validity
   • Verify the version format (e.g., 1.0.1)

Support

• Issues: GitHub Issues
• Repository: GitHub Repository

License

MIT License - see LICENSE file for details.

Made with ❤️ by the SuperPe team