AppHive CLI

Command-line tool for uploading Flutter code push patches to AppHive.

Installation

npm install -g apphive-cli

Or use locally:

npm install apphive-cli
npx apphive --help

Quick Start

1. Login:

   apphive login

   Follow the prompts to enter your username, password, and select a profile.

   Or use API key directly:

   apphive login --api-key vcs_your-api-key-here

2. Initialize Flutter SDK (automatically uses your API key and backend URL):

   apphive init

   This command:

   • Creates apphive.yaml in your project root with your API key and backend URL
   • Generates Flutter initialization code ready to copy to your main.dart file
   • No manual configuration needed!

   Or save Dart code directly to a file:

   apphive init --file lib/apphive_config.dart

   Skip YAML file creation:

   apphive init --no-yaml

3. Push a patch (automated - recommended):

   apphive patch

   This command automatically:

   • Detects your Flutter project
   • Reads app ID from apphive.yaml
   • Reads version codes from pubspec.yaml
   • Creates a patch ZIP from your lib/ and assets/ directories
   • Uploads and creates the patch

   Or manually specify options:

   apphive patch -a <app-id> --from 1 --to 2

   Or use the manual push command:

   apphive push \
     -a <app-id> \
     -f ./patch.zip \
     --from 1 \
     --to 2

4. List patches:

   apphive patches -a <app-id>

5. Check for patches:

   apphive check -p com.example.app -v 1

Commands

apphive login

Authenticate with AppHive. You can use either username/password or API key.

Options:

• --api-key <key> - Use API key for authentication (recommended for CI/CD)
• --username <username> - Username (can also be entered interactively)
• --password <password> - Password (not recommended, use interactive prompt)
• --profile-key <key> - Profile key to select after login
• --backend-url <url> - Backend URL (overrides saved config and environment variable)
• --logout - Log out and clear credentials

Examples:

# Interactive login
apphive login

# API key login
apphive login --api-key vcs_your-api-key

# Logout
apphive login --logout

apphive init

Initialize AppHive in your Flutter project. Creates apphive.yaml config file and generates Flutter initialization code.

Options:

• -f, --file <path> - Save Dart code to file path (if not provided, prints to console)
• --no-yaml - Skip creating apphive.yaml file
• --overwrite - Overwrite existing files if they exist

Examples:

# Create apphive.yaml and print initialization code
apphive init

# Save Dart code to a file
apphive init --file lib/apphive_config.dart

# Skip YAML file creation
apphive init --no-yaml

# Overwrite existing files
apphive init --overwrite

What it creates:

1. apphive.yaml - Configuration file in your project root:

   api_key: vcs_your-api-key
   backend_url: https://your-backend-url.com

2. Flutter initialization code - Ready to copy to your main.dart

Note:

• You must be logged in first (apphive login)
• The command uses your saved API key and backend URL from your CLI session
• Add apphive.yaml to your .gitignore (contains sensitive API key)

apphive patch ⚡ (Recommended)

Automatically create and push a patch with a single command. This is the easiest way to push patches!

What it does:

1. ✅ Detects Flutter project (checks for pubspec.yaml)
2. ✅ Reads app ID from apphive.yaml (or prompts)
3. ✅ Reads version codes from pubspec.yaml (or prompts)
4. ✅ Creates patch ZIP from lib/ and assets/ directories
5. ✅ Uploads and creates the patch

Options:

• -a, --app-id <id> - App ID (auto-detected from apphive.yaml if not provided)
• -f, --from <code> - From version code (auto-detected from pubspec.yaml if not provided)
• -t, --to <code> - To version code (auto-detected from pubspec.yaml if not provided)
• --file <path> - Use existing patch ZIP file instead of creating one

Examples:

# Fully automated - just run from your Flutter project root
apphive patch

# Specify app ID manually
apphive patch -a 550e8400-e29b-41d4-a716-446655440000

# Specify version codes manually
apphive patch --from 1 --to 2

# Use existing patch file
apphive patch --file ./my-patch.zip

Requirements:

• Must be run from Flutter project root (where pubspec.yaml exists)
• apphive.yaml should contain app_id (or use -a flag)
• pubspec.yaml should have version like "1.0.0+2" (the number after + is the build number)
• lib/ or assets/ directories must exist

Note: The command creates a temporary ZIP file and cleans it up automatically after upload.

apphive push

Upload and create a patch for an app (manual method).

Required Options:

• -a, --app-id <id> - App ID (UUID)
• -f, --file <path> - Path to patch ZIP file
• --from <code> - From version code (integer)
• --to <code> - To version code (integer)

Optional Options:

• -v, --version-id <id> - Version ID (uses latest if omitted)
• --base-url <url> - Backend base URL (overrides config)

Example:

apphive push \
  -a 550e8400-e29b-41d4-a716-446655440000 \
  -f ./patch.zip \
  --from 1 \
  --to 2

Workflow:

1. Validates the patch file
2. Calculates SHA-256 checksum
3. Gets upload configuration from backend
4. Uploads patch file to File Service
5. Creates patch record in backend

apphive patches

List all patches for an app.

Required Options:

• -a, --app-id <id> - App ID (UUID)

Optional Options:

• -p, --page <number> - Page number (default: 1)
• -l, --limit <number> - Items per page (default: 50)

Example:

apphive patches -a 550e8400-e29b-41d4-a716-446655440000

apphive check

Check for available patches (same endpoint used by Flutter SDK).

Required Options:

• -p, --package-name <name> - App package name (e.g., com.example.app)
• -v, --version-code <code> - Current version code (integer)

Example:

apphive check -p com.example.app -v 1

Configuration

Configuration is stored in ~/.apphive/config.json.

Environment Variables:

• APPHIVE_BACKEND_URL - Backend API URL (default: https://api.apphive.com)
• APPHIVE_FILESERVICE_URL - File Service URL (default: https://fileservice.apphive.com)
• APPHIVE_FILESERVICE_API_KEY - File Service API key (for patch uploads)

Example:

export APPHIVE_BACKEND_URL=https://api.example.com
export APPHIVE_FILESERVICE_URL=https://fileservice.example.com
apphive push -a <app-id> -f patch.zip --from 1 --to 2

Generate Flutter SDK Config:

After logging in, use apphive init to automatically generate Flutter initialization code and apphive.yaml config file:

apphive login
apphive init  # Creates apphive.yaml and generates initialization code

Important: Add apphive.yaml to your Flutter project's .gitignore since it contains your API key:

# AppHive config (contains sensitive API key)
apphive.yaml

No need to manually copy API keys or URLs - the CLI handles it automatically!

Authentication

JWT Authentication (Interactive)

Use apphive login without flags for interactive login:

1. Enter username
2. Enter password
3. Select a profile (if multiple profiles available)
4. JWT token is stored automatically

API Key Authentication

Use apphive login --api-key <key> to store an API key. This is recommended for CI/CD environments.

API keys can be obtained from your AppHive dashboard.

Examples

Basic Patch Upload

# Login
apphive login

# Upload patch
apphive push \
  -a 550e8400-e29b-41d4-a716-446655440000 \
  -f ./build/patch.zip \
  --from 1 \
  --to 2

CI/CD Integration

# Set API key
export APPHIVE_API_KEY=vcs_your-api-key

# Login with API key
apphive login --api-key $APPHIVE_API_KEY

# Upload patch
apphive push \
  -a $APP_ID \
  -f ./patch.zip \
  --from $FROM_VERSION \
  --to $TO_VERSION

Check for Updates

# Check if patch is available
apphive check -p com.example.app -v 1

Troubleshooting

"Not authenticated" error

Run apphive login to authenticate first.

"Invalid API key" error

Check that your API key starts with vcs_ and is correct.

"File not found" error

Ensure the patch file path is correct and the file exists.

"Network error"

Check your internet connection and verify the backend URL is correct:

export APPHIVE_BACKEND_URL=https://your-backend-url.com

Development

Building from Source

git clone https://github.com/apphive/apphive-cli.git
cd apphive-cli
npm install
npm link  # Link globally for testing

Testing Locally

# Run commands directly
node bin/apphive push -a <app-id> -f patch.zip --from 1 --to 2

License

MIT

Support

For issues and questions:

• GitHub Issues: https://github.com/apphive/apphive-cli/issues
• Documentation: https://docs.apphive.com