CLI Reference

The AppSpacer CLI (appspacer) is a command-line tool for pushing OTA updates to your React Native apps, managing deployments, and configuring native project files — all from your terminal.

Installation

Install the CLI globally via npm:

npm install -g appspacer-cli

Or run commands on-demand with npx:

npx appspacer <command>

After installation, the appspacer binary is available system-wide.

Configuration

The CLI stores configuration in ~/.appspacer/config.json. This file is created automatically when you first run appspacer login.

You can override the API URL at login time:

appspacer login --api-url https://your-backend.example.com/api

Commands

appspacer login

Authenticate with the AppSpacer backend using a Personal Access Token (PAT).

# Interactive — prompts for token
appspacer login
 
# Non-interactive — pass token directly
appspacer login -t pat_d614b9fcc6d5f5181c04b729e09f7b687ae71e90
 
# Custom backend URL
appspacer login -t pat_xxxx --api-url https://your-backend.example.com/api

Options:

Tokens are generated from the AppSpacer dashboard under Settings → Tokens.

On success, the CLI verifies your token and displays your identity:

✓ Logged in as Jane Doe (jane@company.com)

appspacer whoami

Display the currently authenticated user.

appspacer whoami

✓ Logged in as Jane Doe (jane@company.com)

appspacer setup

Auto-configure your React Native project’s native files for OTA updates. This is the recommended way to set up AppSpacer — it handles all native code injection automatically.

# Run from your React Native project root
appspacer setup

What it does:

1. Verifies react-native-appspacer is installed in node_modules
2. Detects your Android project structure and React Native architecture
3. Injects the correct bundle resolver into MainApplication.kt
4. Configures AppDelegate.mm or AppDelegate.swift for iOS
5. Creates backup files (.appspacer.bak) before making changes

Options:

Examples:

# Full setup — Android + iOS
appspacer setup
 
# Preview what would change
appspacer setup --dry-run
 
# Only configure Android
appspacer setup --android-only
 
# Project in a different directory
appspacer setup --project-dir ./my-react-native-app

Architecture detection:

The CLI automatically detects which React Native architecture pattern your project uses:

The correct injection code is chosen automatically based on the detected architecture.

appspacer setup:undo

Remove all AppSpacer injections from your native files. Restores original code by removing content between // APPSPACER_START and // APPSPACER_END markers.

appspacer setup:undo

Options:

appspacer release

Upload a pre-built JS bundle zip and create an OTA release. Use this when you have a manually built bundle file.

appspacer release \
  -a my-app-android \
  -d Staging \
  -p android \
  -f ./release.zip \
  -t "1.0.0" \
  --description "Fixed login crash" \
  --mandatory

Options:

Upload flow:

1. Requests a presigned upload URL from the server
2. Streams the file to cloud storage with a progress bar
3. Creates a release record linking the uploaded file to the deployment

Output on success:

✓ Release created successfully!
  Platform:   android
  Deployment: Staging
  Target:     1.0.0
  Bundle:     https://storage.example.com/bundles/update.zip
  Size:       245.3 KB
  Release ID: 8f3a2c1e-...

appspacer release-react-native

The recommended release command for React Native projects. Automatically bundles your app, packages it into a zip, computes the SHA-256 hash, uploads, and creates the release — all in one step.

appspacer release-react-native <platform> [options]

Arguments:

Options:

Examples:

# Push a staging update for Android
appspacer release-react-native android \
  -a my-app-android \
  -d Staging \
  -t 1.0.0 \
  --description "Bug fix for checkout flow"
 
# Push a mandatory production update for iOS
appspacer release-react-native ios \
  -a my-app-ios \
  -d Production \
  -t 1.2.0 \
  --description "Critical security patch" \
  --mandatory
 
# Include assets (images, fonts, etc.)
appspacer release-react-native android \
  -a my-app-android \
  -d Staging \
  -t 1.0.0 \
  --include-assets

Automated pipeline:

1. Bundle — Runs npx react-native bundle for the target platform
2. Package — Zips the build output into update.zip
3. Hash — Computes SHA-256 hash for integrity verification
4. Upload — Streams the zip to cloud storage with progress bar
5. Release — Creates a release record on the server
6. Cleanup — Removes temporary build artifacts

appspacer deployments

List all deployments (e.g. Staging, Production) for an app, along with their deployment keys.

appspacer deployments -a my-app-android

Options:

Output:

Deployments (2):

  Staging
    Key: sk_abc123...

  Production
    Key: sk_def456...

Use these deployment keys in your SDK configuration (deploymentKey parameter).

appspacer rollback

Roll back the latest release for a specific deployment and platform. This disables the most recent release and re-activates the previous one.

appspacer rollback \
  -a my-app-android \
  -d Production \
  -p android

Options:

Output:

✓ Rollback successful!
  Disabled Release: v5 (v5)
  Now Active:       v4 (v4)

Common Workflows

First Time Setup

# 1. Install the CLI
npm install -g appspacer-cli
 
# 2. Authenticate with a Personal Access Token
appspacer login -t pat_your_token_here
 
# 3. Install the SDK in your React Native project
cd my-react-native-app
npm install react-native-appspacer
 
# 4. Auto-configure native files
appspacer setup
 
# 5. Rebuild your app
npx react-native run-android
npx react-native run-ios

Publishing an Update

# Push to staging first
appspacer release-react-native android \
  -a my-app \
  -d Staging \
  -t 1.0.0 \
  --description "New feature: dark mode"
 
# Test on staging, then promote to production
appspacer release-react-native android \
  -a my-app \
  -d Production \
  -t 1.0.0 \
  --description "New feature: dark mode"

Rolling Back a Bad Release

# Something went wrong — roll back immediately
appspacer rollback -a my-app -d Production -p android
 
# Verify the rollback
appspacer deployments -a my-app

Exit Codes

Troubleshooting