AppHive CLI

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

Installation

``bash
npm install -g apphive-cli
`

Or use locally:

`bash
npm install apphive-cli
npx apphive --help
`

Quick Start

1. Login:

`bash
apphive login
`

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

Or use API key directly:

`bash
apphive login --api-key vcs_your-api-key-here
`

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

`bash
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:

`bash
apphive init --file lib/apphive_config.dart
`

Skip YAML file creation:

`bash
apphive init --no-yaml
`

3. Push a patch (automated - recommended):

`bash
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:

`bash
apphive patch -a --from 1 --to 2
`

Or use the manual push command:

`bash
apphive push \
-a \
-f ./patch.zip \
--from 1 \
--to 2
`

4. List patches:

`bash
apphive patches -a
`

5. Check for patches:
`bash
apphive check -p com.example.app -v 1
`

Commands

$3

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

Options:

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

Examples:

`bash


Interactive login

apphive login

API key login

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

Logout

apphive login --logout
`

$3

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

Options:

- -f, --file - 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:

`bash


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:

`yaml
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)

$3

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 - App ID (auto-detected from apphive.yaml if not provided)
- -f, --from - From version code (auto-detected from pubspec.yaml if not provided)
- -t, --to - To version code (auto-detected from pubspec.yaml if not provided)
- --file - Use existing patch ZIP file instead of creating one

Examples:

`bash


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.

$3

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

Required Options:

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

Optional Options:

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

Example:

`bash
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

$3

List all patches for an app.

Required Options:

- -a, --app-id - App ID (UUID)

Optional Options:

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

Example:

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

$3

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

Required Options:

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

Example:

`bash
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:

`bash
export APPHIVE_BACKEND_URL=https://api.example.com
export APPHIVE_FILESERVICE_URL=https://fileservice.example.com
apphive push -a -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:

`bash
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:

`gitignore


AppHive config (contains sensitive API key)


apphive.yaml
`

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

Authentication

$3

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

$3

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

API keys can be obtained from your AppHive dashboard.

Examples

$3

`bash


Login

apphive login

Upload patch

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

$3

`bash


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
`

$3

`bash


Check if patch is available


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

Troubleshooting

$3

Run apphive login to authenticate first.

$3

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

$3

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

$3

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

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

Development

$3

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

$3

`bash


Run commands directly


node bin/apphive push -a -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