APK Catalog CLI

Command-line interface for APK Catalog Server - Simplify APK management and deployment.

Installation

npm install -g @apk-catalog/cli

Quick Start

1. Login (Configure CLI)

apk-catalog login

You'll be prompted for:

• Server URL (e.g., https://)
• Admin API Key

2. Upload an APK

Interactive mode:

apk-catalog upload

Direct mode (with all parameters):

apk-catalog upload myapp.apk \
  --app-id com.myapp \
  --label "My App" \
  --version 1.0.2 \
  --notes "Bug fixes" \
  --overwrite

Semi-interactive mode:

apk-catalog upload myapp.apk
# Will prompt for missing parameters

Commands

Authentication & Configuration

# Login (configure CLI)
apk-catalog login

# Logout (clear config)
apk-catalog logout

# Manage configuration
apk-catalog config set <key> <value>
apk-catalog config get <key>
apk-catalog config list

Upload APK/AAB

# Interactive upload
apk-catalog upload

# Upload with parameters
apk-catalog upload <apk-file|aab-file> [options]

Options:
  --app-id <id>              Application ID (e.g., com.app.preview)
  --label <label>            Application label
  --version <version>        Version number (e.g., 1.0.2)
  --notes <notes>            Release notes
  --description <desc>       Short app description
  --category <category>      App category (e.g., Productivity, Tools)
  --overwrite                Overwrite if exists

APK/AAB Support (Unified Async Processing):

• Both .apk and .aab uploads use async processing (since v1.1.0)
• APK: Automatic icon extraction + metadata parsing
• AAB: Generates universal APK + optimized APK sets
• Background processing via job queue
• Track progress with apk-catalog jobs status <jobId>
• Both return 202 Accepted with a jobId for status polling

Catalog Management

# List all apps
apk-catalog catalog list

# Get app details (includes AAB split info)
apk-catalog catalog get <app-id>

# Delete an app
apk-catalog catalog delete <app-id>

# Show statistics
apk-catalog catalog stats

# Export catalog as static files
apk-catalog catalog export [options]

Export Options:

--output <path>       Output file path (default: ./catalog-export.zip)
--base-url <url>      Base URL for static hosting
--relative            Use relative URLs
--include-aabs        Include AAB source files

Job Management (APK/AAB Processing)

# Check job status
apk-catalog jobs status <jobId>

# List jobs for a specific app
apk-catalog jobs list <appId>

# Show queue statistics
apk-catalog jobs stats

# Retry a failed job
apk-catalog jobs retry <jobId>

# Remove a job from queue
apk-catalog jobs remove <jobId>

Note: Since v1.1.0, both APK and AAB uploads create jobs in the processing queue.

Branding Commands

Manage server-side branding configuration for the mobile app:

# Get current branding configuration
apk-catalog branding get

# Set branding configuration interactively
apk-catalog branding set

# Set branding with flags
apk-catalog branding set \
  --name "My Company" \
  --subtitle "Enterprise Apps" \
  --logo-url "https://example.com/logo.png" \
  --primary-color "#2563EB" \
  --accent-color "#10B981"

# Reset branding to defaults
apk-catalog branding reset

Branding Options: | Option | Description | |--------|-------------| | --name <name> | Organization name | | --subtitle <subtitle> | Organization subtitle | | --logo-url <url> | URL to organization logo | | --primary-color <hex> | Primary theme color (e.g., #2563EB) | | --accent-color <hex> | Accent theme color (e.g., #10B981) |

Admin Commands

# System health
apk-catalog admin health

# Storage information
apk-catalog admin storage-info

# Test storage
apk-catalog admin storage-test

# Cleanup orphaned files
apk-catalog admin cleanup

# Migration (dual storage)
apk-catalog admin migrate start
apk-catalog admin migrate status
apk-catalog admin migrate stop

Server Info & Health

# Get server information
apk-catalog info

# Quick health check
apk-catalog health

Static Catalog Server

Start a local static server to host exported catalogs. Perfect for testing, development, or local distribution.

# Serve an exported catalog
apk-catalog serve <path-to-catalog-or-zip>

# Custom port and host
apk-catalog serve ./catalog.zip --port 8080 --host 0.0.0.0

# Verbose logging
apk-catalog serve ./catalog-export/ --verbose

Options:

• --port, -p <port> - Port to listen on (default: 8080)
• --host, -h <host> - Host to bind to (default: 0.0.0.0)
• --verbose, -v - Show detailed request logs

Features:

• ✅ Serves exported catalog directories or ZIP files
• ✅ Automatically extracts ZIP files to temporary directory
• ✅ Transforms URLs to point to local server
• ✅ Displays QR code for easy mobile app configuration
• ✅ Compatible with mobile app catalog endpoint
• ✅ CORS enabled for cross-origin requests
• ✅ Health check endpoint (notifications not supported)

Shell Autocompletion

The CLI supports shell autocompletion for commands, options, and arguments to improve productivity.

Install Autocompletion

Automatic installation (recommended):

# Auto-detect shell and install
apk-catalog completion install

# Force specific shell
apk-catalog completion install --shell bash
apk-catalog completion install --shell zsh

Manual installation:

# Generate bash completion script
apk-catalog completion bash --output ./apk-catalog-completion.bash
source ./apk-catalog-completion.bash

# Generate zsh completion script
apk-catalog completion zsh --output ./_apk-catalog
# Copy to completion directory and configure .zshrc

Autocompletion Features

Commands and options:

apk-catalog <TAB>          # Shows: upload, catalog, jobs, admin, serve, etc.
apk-catalog upload <TAB>   # Shows: --app-id, --label, --version, etc.
apk-catalog jobs <TAB>     # Shows: status, list, stats, retry, etc.
apk-catalog serve <TAB>    # Shows: --port, --host, --verbose

File paths:

apk-catalog upload <TAB>   # Shows APK/AAB files in current directory
apk-catalog upload my<TAB> # Filters to files starting with "my"
apk-catalog serve <TAB>    # Shows ZIP files and directories
apk-catalog serve cat<TAB> # Completes to catalog-export.zip

App IDs and versions:

apk-catalog catalog get <TAB>     # Shows available app IDs from server
apk-catalog jobs list <TAB>       # Shows app IDs for job filtering

Setup Instructions

After installation, restart your terminal or source your shell configuration:

# For bash
source ~/.bashrc

# For zsh
source ~/.zshrc

Note: Shell autocompletion requires a configured CLI (run apk-catalog login first) for dynamic suggestions like app IDs.

Interactive Autocompletion

When using interactive mode, the CLI provides intelligent autocompletion within prompts.

File Selection Autocompletion

apk-catalog upload
# ? Select APK/AAB file: (Use arrow keys or type to search)
#   📦 app-release.apk (12.3 MB)
#   📦 app-debug.aab (8.7 MB)
#   📁 ../builds/
#   📁 ./archive/

Features:

• Smart filtering: Only shows .apk and .aab files
• Directory navigation: Browse folders with arrow keys
• File size display: Shows file sizes for easy identification
• Fuzzy search: Type partial names to filter results
• Magic number validation: Verifies file headers before upload

Version Autocompletion

apk-catalog upload myapp.apk
# ? Enter version: (Use arrow keys or type to search)
#   🎯 1.0.3 (next patch)
#   🎯 1.1.0 (next minor)
#   📋 1.0.2 (current)
#   📋 1.0.1
#   ✏️  Type custom version...

Smart suggestions:

• Semantic versioning: Suggests next patch/minor/major versions
• Custom patterns: Supports any version format (1.0.2-beta, 2024.01.15)
• Historical versions: Shows existing versions for reference
• Validation: Matches server pattern /^[\d\w\.\-]+$/

App ID Autocompletion

apk-catalog catalog get
# ? Select app ID: (Use arrow keys or type to search)
#   📱 com.myapp.production (MyApp Production)
#   📱 com.myapp.staging (MyApp Staging)
#   📱 com.example.demo (Demo App)
#   ✏️  Type custom app ID...

Features:

• Live catalog sync: Fetches current apps from server
• App labels: Shows friendly names alongside package IDs
• Fuzzy search: Type partial IDs to filter quickly
• Custom input: Option to enter new app IDs

Job Monitoring with Watch

Monitor APK/AAB processing jobs in real-time with automatic updates.

# Start watching a job
apk-catalog jobs watch <jobId>

# Custom polling interval
apk-catalog jobs watch <jobId> --interval 5

Watch output example:

$ apk-catalog jobs watch package-processing:com.example.app-1.0.0-1234567890

🔄 Watching job: package-processing:com.example.app-1.0.0-1234567890
Press Ctrl+C to stop watching...

[14:32:15] Status: ACTIVE     Progress: ████████░░░░░░░░░░░░ 40%
[14:32:17] Status: ACTIVE     Progress: ███████████░░░░░░░░░ 55%
[14:32:19] Status: ACTIVE     Progress: ███████████████░░░░░ 75%
[14:32:21] Status: COMPLETED  Progress: ████████████████████ 100%

✅ Job completed successfully!

📦 Generated Files:
  Universal APK: com.example.app-1.0.0-universal.apk (52.43 MB)
  APK Set:       com.example.app-1.0.0.apks (45.67 MB)

🏗️  Build Details:
  ABIs:     arm64-v8a, armeabi-v7a, x86_64
  DPIs:     hdpi, xhdpi, xxhdpi
  Locales:  en, fr, es

Features:

• Real-time updates: Automatic polling with configurable interval (default: 2s)
• Progress visualization: ASCII progress bars with percentage
• Timestamps: Each update shows current time
• Completion details: Full job summary when finished
• Error handling: Shows detailed error messages on failure
• Graceful exit: Ctrl+C to stop watching

Usage Examples

AAB Upload & Monitoring

#!/bin/bash

# Upload AAB file (with interactive autocompletion)
apk-catalog upload
# CLI will prompt with autocompletion for:
# - File selection (shows only .aab files)
# - App ID (suggests from existing catalog)
# - Version (suggests intelligent increments)
# - Label and notes

# Or direct upload with parameters
RESULT=$(apk-catalog upload app-release.aab \
  --app-id com.myapp.production \
  --label "MyApp (Production)" \
  --version "${CI_BUILD_VERSION}" \
  --notes "Build #${CI_BUILD_NUMBER}" \
  --overwrite)

# Extract job ID from output
JOB_ID=$(echo "$RESULT" | grep "Job ID:" | awk '{print $3}')

# Monitor with real-time watch (NEW FEATURE)
echo "Watching AAB processing in real-time..."
apk-catalog jobs watch "$JOB_ID"

# Alternative: Poll manually
echo "Monitoring AAB processing..."
while true; do
  STATUS=$(apk-catalog jobs status "$JOB_ID" 2>&1)

  if echo "$STATUS" | grep -q "completed"; then
    echo "✓ AAB processing completed"
    break
  elif echo "$STATUS" | grep -q "failed"; then
    echo "✗ AAB processing failed"
    exit 1
  fi

  sleep 5
done

# Verify in catalog
apk-catalog catalog get com.myapp.production

CI/CD Integration (APK)

#!/bin/bash

# Upload APK in CI/CD pipeline
apk-catalog upload app-release.apk \
  --app-id com.myapp.production \
  --label "MyApp (Production)" \
  --version "${CI_BUILD_VERSION}" \
  --notes "Build #${CI_BUILD_NUMBER}" \
  --overwrite

# Check if upload was successful
if [ $? -eq 0 ]; then
  echo "✓ APK uploaded successfully"
else
  echo "✗ Upload failed"
  exit 1
fi

Update Workflow

# 1. Upload new version (interactive mode with autocompletion)
apk-catalog upload
# Use TAB completion for file selection and version suggestions

# Or direct upload
apk-catalog upload myapp-1.0.3.aab --overwrite

# 2. Monitor AAB processing with watch
apk-catalog jobs watch <jobId>

# 3. Check job queue status
apk-catalog jobs stats
apk-catalog jobs list com.myapp

# 4. Verify upload with autocompletion
apk-catalog catalog get <TAB>  # Shows available app IDs

# 5. Check system health
apk-catalog admin health

Static Catalog Export

# Export catalog for CDN deployment (with shell completion)
apk-catalog catalog export \
  --output ./my-catalog.zip \
  --base-url https://cdn.example.com/catalog

# Interactive mode for export options
apk-catalog catalog export
# CLI will prompt for output path, base URL, and options

# Export with relative URLs (for flexible hosting)
apk-catalog catalog export \
  --output ./catalog.zip \
  --relative

# Export with AAB source files included
apk-catalog catalog export \
  --output ./catalog-full.zip \
  --base-url https://cdn.example.com \
  --include-aabs

Enhanced CLI Features Demo

# 1. Setup shell autocompletion
apk-catalog completion install

# 2. Interactive upload with all autocompletion features
apk-catalog upload
# ✨ File selection shows:    📦 app.aab (15.2 MB)
# ✨ App ID suggestions:      📱 com.myapp.prod (MyApp Production)
# ✨ Version suggestions:     🎯 1.0.3 (next patch)

# 3. Real-time job monitoring
apk-catalog jobs watch aab-com.myapp.prod-1.0.3-123456
# 🔄 Watching job with live progress bars and timestamps

# 4. Shell completion in action
apk-catalog catalog <TAB>    # list, get, delete, stats, export
apk-catalog jobs <TAB>       # status, list, stats, retry, remove, watch
apk-catalog jobs list <TAB>  # Shows app IDs from server
apk-catalog serve <TAB>      # Shows ZIP files and directories

# 5. Static server with auto QR code
apk-catalog catalog export --relative
apk-catalog serve ./catalog-export.zip
# 📱 QR code displayed automatically for mobile configuration

# 6. Enhanced error handling
apk-catalog upload invalid.txt
# ❌ Invalid APK/AAB file: File format not recognized
# 💡 Suggestion: Ensure file is a valid APK or AAB (ZIP format)
# 💡 Check with: file invalid.txt

Configuration

The CLI stores configuration in ~/.config/apk-catalog-cli/config.json:

• apiUrl: Server URL
• apiKey: Admin API key

Update CLI

The CLI automatically checks for updates every 24 hours. To manually update:

npm install -g @apk-catalog/cli@latest

Development

# Clone repository
git clone <repo-url>
cd cli

# Install dependencies
npm install

# Run in development mode
npm run dev -- <command>

# Build
npm run build

# Test built CLI
node dist/index.js <command>

Package Processing (APK & AAB)

Unified Async Processing

Since v1.1.0, both APK and AAB uploads use async processing via the job queue:

APK Processing:

1. Upload APK: CLI detects .apk extension
2. Async Processing: Server queues job for background processing
3. Icon Extraction: Automatic icon extraction and metadata parsing
4. Catalog Update: Automatically updates catalog when processing completes

AAB Processing:

1. Upload AAB: CLI detects .aab extension
2. Async Processing: Server queues job for background processing
3. Dual Output:
   • Universal APK (works on all devices)
   • APK Set (.apks file with device-specific splits)
4. Catalog Update: Automatically updates catalog when processing completes

Upload Flow

# Upload APK or AAB
$ apk-catalog upload myapp.apk \  # or myapp.aab
    --app-id com.example.app \
    --label "My App" \
    --version 1.0.0

# Output (same for both APK and AAB):
# ✓ Package uploaded successfully!
#
# 🔄 Processing Job:
# ──────────────────────────────────────────────────────────
# Job ID:      package-processing:com.example.app-1.0.0-1234567890
# App ID:      com.example.app
# Version:     1.0.0
# Type:        apk (or aab)
# Status URL:  /api/jobs/package-processing:com.example.app-1.0.0-1234567890
# ──────────────────────────────────────────────────────────
#
# ⏳ Processing in background...
#    APK: Icon extraction and metadata parsing.
#    AAB: Conversion to APK sets.
#
#    Track progress with:
#    apk-catalog jobs status package-processing:com.example.app-1.0.0-1234567890

Monitor Processing

# Check job status
$ apk-catalog jobs status package-processing:com.example.app-1.0.0-1234567890

# Output:
# 🔄 Job Status:
# ────────────────────────────────────────────────────────────
# Job ID:      package-processing:com.example.app-1.0.0-1234567890
# App ID:      com.example.app
# Version:     1.0.0
# Type:        aab
# Status:      COMPLETED
# Progress:    ████████████████████ 100%
# ────────────────────────────────────────────────────────────
#
# 📦 Generated Files (AAB):
#
#   Universal APK:
#     File:     com.example.app-1.0.0-universal.apk
#     Size:     52.43 MB
#     SHA-256:  abc123def456...
#
#   APK Set (.apks):
#     File:     com.example.app-1.0.0.apks
#     Size:     45.67 MB
#
#   Splits:
#     ABIs:     arm64-v8a, armeabi-v7a, x86_64
#     DPIs:     hdpi, xhdpi, xxhdpi
#     Locales:  en, fr, es

# For APK jobs, the output shows:
# 📦 Processed Files (APK):
#   APK:        com.example.app-1.0.0.apk
#   Size:       25.0 MB
#   SHA-256:    abc123def456...
#   Icon:       ✓ Extracted

Queue Management

# View queue statistics
$ apk-catalog jobs stats

# Output:
# 📊 Queue Statistics:
# ────────────────────────────────────────
# Waiting:    2
# Active:     1
# Completed:  15
# Failed:     0
# ────────────────────────────────────────
# Total:      18

# List all jobs for an app
$ apk-catalog jobs list com.example.app

# Retry failed job
$ apk-catalog jobs retry <jobId>

# Remove job from queue
$ apk-catalog jobs remove <jobId>

Static Export

What is Static Export?

Export your entire catalog as a ZIP archive ready for deployment to static hosting (CDN, GitHub Pages, S3, etc.). This provides:

• Better Performance: Serve files from CDN instead of your server
• Offline Support: Host catalog without running the server
• Cost Reduction: No server costs for static hosting
• Global Distribution: CDN edge locations for faster downloads

Export Workflow

# 1. Export catalog
apk-catalog catalog export \
  --output ./catalog.zip \
  --base-url https://cdn.example.com/catalog

# 2. Extract and verify
unzip catalog.zip -d catalog-static
cd catalog-static
cat README.md  # Read deployment instructions

# 3. Deploy to hosting service
# See README.md for specific instructions

# 4. Update mobile app configuration
# Point manifestUrl to: https://cdn.example.com/catalog/catalog.json

Export Options Explained

--base-url <url>

• Sets the base URL for all file references in catalog
• Example: --base-url https://cdn.example.com/catalog
• Catalog will contain: https://cdn.example.com/catalog/apks/app.apk

--relative

• Uses relative URLs instead of absolute
• Example: ./apks/app.apk instead of full URL
• Useful for flexible deployment (dev/staging/prod)

--include-aabs

• Includes AAB source files in export
• Useful for archival or if you need original bundles
• Increases export size significantly

Deployment Examples

GitHub Pages:

apk-catalog catalog export --relative
unzip catalog-export.zip -d gh-pages
cd gh-pages
git init && git add . && git commit -m "Catalog"
git push origin gh-pages
# Catalog URL: https://username.github.io/repo/catalog.json

AWS S3:

apk-catalog catalog export --base-url https://cdn.example.com
unzip catalog-export.zip -d catalog
aws s3 sync catalog s3://mybucket --acl public-read
# Catalog URL: https://cdn.example.com/catalog.json

Netlify:

apk-catalog catalog export --base-url https://myapp.netlify.app
unzip catalog-export.zip -d deploy
cd deploy && netlify deploy --prod
# Catalog URL: https://myapp.netlify.app/catalog.json

Local Testing with Static Server

Test your exported catalog locally before deploying:

# 1. Export catalog
apk-catalog catalog export --relative --output ./test-catalog.zip

# 2. Start local static server
apk-catalog serve ./test-catalog.zip

# Output:
# ✅ Extracted to /tmp/apk-catalog-serve-1234567890
#
# ┌─────────────────────────────────────────────────────┐
# │  📦 APK Catalog Static Server                       │
# ├─────────────────────────────────────────────────────┤
# │  Status:  ✅ Running                                 │
# │  Host:    192.168.1.14:8080                         │
# │  Apps:    3 applications                            │
# │  Version: 1.0.0                                     │
# ├─────────────────────────────────────────────────────┤
# │  📱 Scan QR Code to Configure Mobile App:           │
# │                                                     │
# │        [QR CODE ASCII ART]                          │
# │                                                     │
# ├─────────────────────────────────────────────────────┤
# │  URLs:                                              │
# │  • Catalog: http://192.168.1.14:8080/api/catalog    │
# │  • Manual:  http://192.168.1.14:8080                │
# ├─────────────────────────────────────────────────────┤
# │  Press Ctrl+C to stop server                        │
# └─────────────────────────────────────────────────────┘

# 3. Configure mobile app by scanning QR code or manually enter:
#    http://192.168.1.14:8080/api/catalog

# 4. Test download and installation from mobile app

# 5. Stop server with Ctrl+C

Development Workflow:

# Export catalog from production server
apk-catalog catalog export --relative

# Serve locally for testing
apk-catalog serve ./catalog-export.zip --verbose

# Make changes, re-export, and restart server
# Ctrl+C to stop, then re-run serve command

# Deploy to production when ready
unzip catalog-export.zip -d production
rsync -av production/ user@server:/var/www/catalog/

QR Code Configuration: The static server automatically generates a QR code that contains:

{
  "type": "apk-catalog-config",
  "apiBaseUrl": "http://192.168.1.14:8080",
  "version": "1.0"
}

Users can scan this QR code with the mobile app to automatically configure the catalog URL.

Note: The static server does not support push notifications. The mobile app will detect this and disable notification features.

Troubleshooting

AAB upload returns 202 but no job processing:

• Check queue stats: apk-catalog jobs stats
• Verify worker is running on server
• Check server logs for Redis connection

Job stuck in "active" state:

• Check job status: apk-catalog jobs status <jobId>
• Use watch command: apk-catalog jobs watch <jobId> for real-time monitoring
• Retry the job: apk-catalog jobs retry <jobId>
• Contact server admin if worker is down

AAB processing failed:

• View job details for error message
• Use watch command to see detailed progress and error logs
• Common issues:
  • Invalid AAB file format
  • Missing bundletool on server
  • Insufficient disk space
  • Keystore errors (for signing)

Export fails with large catalogs:

• Ensure enough disk space
• Check network timeout settings
• Export without AABs: remove --include-aabs flag

Shell autocompletion not working:

• Verify CLI is configured: apk-catalog config list
• Reinstall completion: apk-catalog completion install
• Check shell configuration:
  • Bash: Ensure ~/.bashrc sources completion script
  • Zsh: Verify fpath includes completion directory
• Restart terminal or run: source ~/.bashrc / source ~/.zshrc

Interactive autocompletion shows no suggestions:

• File selection: Check current directory contains APK/AAB files
• App IDs: Verify CLI is logged in and server is accessible
• Versions: Ensure app exists in catalog for version suggestions
• Check network connectivity: apk-catalog health

File validation errors:

• "Invalid APK/AAB file": File may be corrupted or wrong format
• Use file command to verify: file myapp.apk
• Check magic numbers:
  • APK: Should start with PK (ZIP format)
  • AAB: Should start with PK (ZIP format)
• Re-download or rebuild the file if corrupted

Upload progress bar not showing:

• Progress bars only appear for files >10MB
• Check file size: ls -lh myapp.aab
• For smaller files, upload completes quickly without progress indication

Version validation fails:

• CLI uses pattern /^[\d\w\.\-]+$/ (matches server)
• Valid examples: 1.0.0, 2024.01.15, 1.0.0-beta, v1.2.3
• Invalid examples: 1.0.0+build, 1.0.0_rc1, 1.0.0 final
• Use custom version with allowed characters only

Interactive prompts freeze or crash:

• Ensure terminal supports TTY interaction
• Check if running in CI/CD: Use non-interactive mode instead
• Update CLI: npm install -g @apk-catalog/cli@latest
• Clear config and re-login: apk-catalog logout && apk-catalog login

Static server issues:

• "Cannot find module 'string-width'": Run npm install in CLI directory
• QR code not displaying: Terminal may not support Unicode characters
• Port already in use: Change port with --port option or kill process using that port
• Mobile app can't connect:
  • Check firewall allows incoming connections on specified port
  • Verify mobile device is on same network as server
  • Use correct IP address (shown in server output)
  • Try --host 0.0.0.0 to bind to all network interfaces
• ZIP extraction fails: Ensure ZIP file is valid catalog export
• Catalog not found: Verify catalog.json exists in served directory

License

MIT