@apk-catalog/cli
Advanced tools
Command-line interface for APK Catalog Server - Simplify APK management and deployment.
npm install -g @apk-catalog/cli
apk-catalog login
You'll be prompted for:
https://)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
# 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
# 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):
.apk and .aab uploads use async processing (since v1.1.0)apk-catalog jobs status <jobId>202 Accepted with a jobId for status polling# 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
# 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.
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) |
# 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
# Get server information
apk-catalog info
# Quick health check
apk-catalog health
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 logsFeatures:
The CLI supports shell autocompletion for commands, options, and arguments to improve productivity.
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
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
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.
When using interactive mode, the CLI provides intelligent autocompletion within prompts.
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:
.apk and .aab filesapk-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:
1.0.2-beta, 2024.01.15)/^[\d\w\.\-]+$/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:
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:
#!/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
#!/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
# 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
# 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
# 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
The CLI stores configuration in ~/.config/apk-catalog-cli/config.json:
apiUrl: Server URLapiKey: Admin API keyThe CLI automatically checks for updates every 24 hours. To manually update:
npm install -g @apk-catalog/cli@latest
# 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>
Since v1.1.0, both APK and AAB uploads use async processing via the job queue:
APK Processing:
.apk extensionAAB Processing:
.aab extension# 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
# 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
# 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>
Export your entire catalog as a ZIP archive ready for deployment to static hosting (CDN, GitHub Pages, S3, etc.). This provides:
# 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
--base-url <url>
--base-url https://cdn.example.com/cataloghttps://cdn.example.com/catalog/apks/app.apk--relative
./apks/app.apk instead of full URL--include-aabs
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
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.
AAB upload returns 202 but no job processing:
apk-catalog jobs statsJob stuck in "active" state:
apk-catalog jobs status <jobId>apk-catalog jobs watch <jobId> for real-time monitoringapk-catalog jobs retry <jobId>AAB processing failed:
Export fails with large catalogs:
--include-aabs flagShell autocompletion not working:
apk-catalog config listapk-catalog completion install~/.bashrc sources completion scriptfpath includes completion directorysource ~/.bashrc / source ~/.zshrcInteractive autocompletion shows no suggestions:
apk-catalog healthFile validation errors:
file myapp.apkPK (ZIP format)PK (ZIP format)Upload progress bar not showing:
ls -lh myapp.aabVersion validation fails:
/^[\d\w\.\-]+$/ (matches server)1.0.0, 2024.01.15, 1.0.0-beta, v1.2.31.0.0+build, 1.0.0_rc1, 1.0.0 finalInteractive prompts freeze or crash:
npm install -g @apk-catalog/cli@latestapk-catalog logout && apk-catalog loginStatic server issues:
npm install in CLI directory--port option or kill process using that port--host 0.0.0.0 to bind to all network interfacescatalog.json exists in served directoryMIT
FAQs
CLI tool for APK Catalog Server
The npm package @apk-catalog/cli receives a total of 3 weekly downloads. As such, @apk-catalog/cli popularity was classified as not popular.
We found that @apk-catalog/cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A new npm package tests AI malware scanners with prompt injection, safety-triggering comments, context flooding, and obfuscated JavaScript.
Product
Socket now detects supply chain risks in project manifests, starting with missing lockfiles that can make dependency installs non-reproducible.
Research
/Security News
The trojanized extensions use TinyGo-compiled WebAssembly and Solana transaction memos to resolve command-and-control infrastructure.