apexkit

A professional CLI tool for creating Apex Home Application Dashboard live applications

About

apexkit is a command-line interface tool that helps developers quickly scaffold and manage Apex Home Application Dashboard live applications. Apex Home Application Dashboard is an open-source self-hosted productivity-oriented application dashboard that allows you to create custom widgets and integrations.

Features

• Quick scaffolding - Create a complete live app structure in seconds
• Config management - Add and manage application configurations interactively
• Datapoint management - Define and organize data points with ease
• Package & Deploy - Package your app and publish directly to Apex Home Application Dashboard
• Secure Authentication - Login once and publish multiple times
• Built-in validation - Ensures proper naming conventions and data formats
• Icon validation - Validates against lucide-react icon library
• Smart defaults - Intelligent default values based on context

Installation

Global Installation (Recommended)

npm install -g apexkit

Local Installation

npm install apexkit

Using npx (No Installation Required)

npx apexkit liveapp create

Quick Start

Create a New Live App

Navigate to your desired directory and run:

apexkit liveapp create

You'll be prompted for:

• App name (default: current folder name)
• App ID (default: com.foldername, must start with com., lowercase, no special characters)
• App version (default: 1.0.0)
• App website (default: https://example.com)
• Auto refresh in seconds (default: 300)

This generates:

your-app/
├── public/
│   └── logo.svg
├── app.js
├── manifest.json
└── package.json

Add Configuration

Add a configuration field to your live app:

apexkit liveapp add config

Interactive prompts guide you through:

• Config Label (required)
• Config Name (auto-generated, validated)
• Required (yes/no)
• Placeholder text
• Help Link
• Type (password, string, select, checkbox, radio, html, multilinestring)
• Options (for select/radio types)
• Visibility conditions

Add Datapoint

Add a datapoint to your live app:

apexkit liveapp add datapoint

You'll define:

• Datapoint Label (required)
• Datapoint Key (auto-generated, validated)
• Description
• Default Selection (yes/no)
• Icon (validated lucide-react icon name)

Login to Apex Home Application Dashboard

Before publishing, authenticate with your apexkit access token:

apexkit login

You'll be prompted for:

• apexkit access token - Your developer access token

The token is validated and stored securely in ~/.apexkit/token.json for future use.

Package Live App

Package your live app into a deployable zip file:

apexkit liveapp package

This command:

• Verifies all required files exist (public/, app.js, manifest.json, package.json)
• Creates a zip file named {appId}.zip
• Places the zip in an output/ folder
• Provides clear instructions for deployment

Output:

output/
└── com.yourapp.zip

Publish Live App

Publish your live app directly to Apex Home Application Dashboard:

apexkit liveapp publish

This command:

• Checks for saved authentication token (prompts to login if not found)
• Creates a deployment package
• Uploads your app to Apex Home Application Dashboard
• Confirms successful deployment

No manual zip upload needed.

Commands

apexkit liveapp create

Creates a new Apex Home Application Dashboard live application with the following structure:

Generated Files:

app.js

Contains the core functions for your live app:

const connectionTest = async testerInstance => {
  return testerInstance.connectionSuccess();
};

const initialize = async application => {
  const config = application?.config || {};
  try {
    const rawResponse = {
      data: [],
      button: {},
    };
    return application.sendRawResponse(200, rawResponse);
  } catch (error) {
    console.log(error);
    return application.sendError(error);
  }
};

global.initialize = initialize;
global.connectionTest = connectionTest;

manifest.json

Defines your app's metadata and configuration schema.

package.json

Standard Node.js package file for dependency management.

public/logo.svg

Your app's logo (Apex Home Application Dashboard logo by default).

apexkit liveapp add config

Adds a configuration field to your manifest.json.

Validation Rules:

• Config name must be lowercase, no spaces, no special characters
• Config names must be unique
• Config label cannot be empty

Config Types:

• password - Secure password input
• string - Single-line text input
• select - Dropdown selection
• checkbox - Checkbox input
• radio - Radio button selection
• html - HTML content
• multilinestring - Multi-line text input

Example Config Object:

{
  "name": "apikey",
  "label": "API Key",
  "type": "password",
  "required": true,
  "placeholder": "Enter your API key",
  "helpLink": "https://docs.example.com/api-key",
  "visibleIf": {
    "enableapi": "true"
  }
}

Conditional Visibility:

You can make configs visible based on other config values using the visibleIf property. The CLI will:

1. Show you a list of existing configs
2. Let you select which config controls visibility
3. Prompt for the value that triggers visibility

apexkit liveapp add datapoint

Adds a datapoint definition to your manifest.json.

Validation Rules:

• Datapoint key must be lowercase, no spaces, no special characters
• Datapoint keys must be unique
• Datapoint label cannot be empty
• Icon must be a valid lucide-react icon name

Example Datapoint Object:

{
  "key": "status",
  "label": "Status",
  "description": "Health check status",
  "defaultSelection": true,
  "icon": "trending-up"
}

Valid Icons:

Icons are validated against the lucide-react library (v0.263.1). Common examples:

• trending-up, trending-down
• activity, check-circle, alert-triangle
• home, settings, user
• heart, star, bookmark
• See full list: Lucide Icons

apexkit login

Authenticate with Apex Home Application Dashboard using your developer access token.

What it does:

1. Prompts for your apexkit access token
2. Validates the token against the server
3. Saves the token securely in ~/.apexkit/token.json
4. Confirms successful authentication

Usage:

apexkit login

Output:

Apex Home Developer Login

Enter your apexkit access token: **********************

Validating token...

Login successful.
Token validated and saved.

You can now use "apexkit liveapp publish" to publish your apps.

Token Storage:

• Location: ~/.apexkit/token.json (Unix/macOS) or C:\Users\{username}\.apexkit\token.json (Windows)
• Security: Store your token securely and never commit it to version control
• Persistence: Once logged in, you can publish multiple apps without re-entering your token

apexkit liveapp package

Packages your live app into a deployment-ready zip file.

What it does:

1. Verifies all required files exist (public/, app.js, manifest.json, package.json)
2. Creates an output/ directory if it doesn't exist
3. Generates a zip file named {appId}.zip containing all necessary files
4. Places the zip in the output folder

Requirements:

• Windows: PowerShell (included with Windows)
• macOS/Linux: zip utility

  # Ubuntu/Debian
  sudo apt-get install zip
    
  # macOS
  brew install zip

Usage:

cd my-live-app
apexkit liveapp package

Output:

Package created successfully.

Package Details:
  Name: com.myapp.zip
  Location: /path/to/project/output

Your live app is ready for deployment.

Next steps:
  1. Navigate to the output folder: cd output
  2. Upload com.myapp.zip to your Apex Home Application Dashboard instance

Package Contents:

• public/ - All public assets including logo.svg
• app.js - Your application logic
• manifest.json - App configuration and metadata
• package.json - Node.js dependencies

apexkit liveapp publish

Publish your live app directly to Apex Home Application Dashboard with a single command.

What it does:

1. Checks for a saved authentication token
2. Prompts to login if no token is found
3. Validates the token
4. Creates a deployment package (same as apexkit liveapp package)
5. Uploads the package to the server
6. Prompts for a changelog for the release
7. Confirms successful deployment

Usage:

cd my-live-app
apexkit liveapp publish

First-time publish (no saved token):

Publishing Live App

App ID: com.myapp

No access token found. Please login first.

Enter your apexkit access token: **********************

Validating token...

Token validated and saved.

Verifying required files...

All required files found.

Creating package...

Package created successfully.

Please provide a changelog for this release: Initial release

Uploading to Apex Home with changelog...

Your app is now published.

Subsequent publishes (token saved):

Publishing Live App

App ID: com.myapp

Using saved access token.

Verifying required files...

All required files found.

Creating package...

Package created successfully.

Please provide a changelog for this release: Bug fixes and improvements

Uploading to Apex Home with changelog...

Your app is now published.

Requirements:

• Valid apexkit access token
• All required files (public/, app.js, manifest.json, package.json)
• Internet connection
• Zip utility (same as package command)

Error Handling

The CLI includes robust error handling:

Live App Already Exists

apexkit liveapp create
# Error: Live app already exists in this directory.
# Found existing manifest.json, app.js, and package.json

Solution: Navigate to a different directory or remove existing files.

No Live App Found

apexkit liveapp add config
# Error: No live app found in this directory.
# Run "apexkit liveapp create" first.

Solution: Run apexkit liveapp create first.

Duplicate Config/Datapoint

# Error: Config with name "apikey" already exists.

Solution: Choose a different name.

Invalid App ID

# Error: App ID must start with "com."
# Error: App ID must be lowercase with no special characters

Solution: Follow the format com.yourappname (lowercase, no spaces/special chars).

Invalid Icon

# Error: Invalid icon name "invalid-icon". Please use a valid lucide-react icon.
# Example valid icons: trending-up, activity, home, check-circle, alert-triangle

Solution: Use a valid lucide-react icon name.

Missing Required Files

apexkit liveapp package
# Error: Missing required files:
#   - app.js
#   - public/logo.svg

Solution: Ensure all required files exist before packaging.

Zip Utility Not Found

# Error creating package: zip command not found
# Note: Make sure you have zip utility installed on your system.

Solution: Install zip utility for your system (see package command documentation).

Invalid Token

apexkit login
# Login failed.
# Invalid token.

Solution: Verify your apexkit access token and try again.

Token Validation Failed

apexkit liveapp publish
# Token validation failed.
# Invalid token.

Solution: Run apexkit login to update your token.

Publication Failed

apexkit liveapp publish
# Error: [Error message from server]

Solution: Check the error message for specific details. Common issues:

• Invalid app structure
• Missing required fields in manifest.json
• Network connectivity issues

Network Error

# Error during publication: connect ECONNREFUSED
# Please check your internet connection and try again.

Solution: Verify your internet connection and try again.

Manifest Schema

Complete manifest.json Example:

{
  "appName": "Weather Dashboard",
  "appId": "com.weatherdashboard",
  "appIcon": "logo.svg",
  "version": "1.0.0",
  "appWebsite": "https://example.com/weather",
  "description": "Weather Dashboard is an Apex Home Application Dashboard live application.",
  "autoRefreshAfterSeconds": 300,
  "detailedView": "always",
  "type": ["liveapp"],
  "config": [
    {
      "name": "apikey",
      "label": "API Key",
      "type": "password",
      "required": true,
      "placeholder": "Enter your API key",
      "helpLink": "https://openweathermap.org/api"
    },
    {
      "name": "location",
      "label": "Location",
      "type": "string",
      "required": true,
      "placeholder": "City name"
    },
    {
      "name": "units",
      "label": "Temperature Units",
      "type": "select",
      "required": true,
      "options": ["Celsius", "Fahrenheit", "Kelvin"]
    }
  ],
  "datapoints": [
    {
      "key": "temperature",
      "label": "Temperature",
      "description": "Current temperature",
      "defaultSelection": true,
      "icon": "thermometer"
    },
    {
      "key": "humidity",
      "label": "Humidity",
      "description": "Current humidity percentage",
      "defaultSelection": true,
      "icon": "droplet"
    },
    {
      "key": "wind",
      "label": "Wind Speed",
      "description": "Current wind speed",
      "defaultSelection": false,
      "icon": "wind"
    }
  ]
}

Workflow Example

Here's a typical workflow for creating and publishing a new live app:

# 1. Create a new directory
mkdir my-awesome-app
cd my-awesome-app

# 2. Create the live app structure
apexkit liveapp create
# Enter app details when prompted

# 3. Add configuration fields
apexkit liveapp add config
# Add API key config

apexkit liveapp add config
# Add URL config

# 4. Add datapoints
apexkit liveapp add datapoint
# Add status datapoint

apexkit liveapp add datapoint
# Add response time datapoint

# 5. Implement your logic in app.js
# Edit app.js to add your custom functionality

# 6. Install dependencies (if needed)
npm install
# Add your custom dependencies

# 7. Login to Apex Home Application Dashboard (first time only)
apexkit login
# Enter your apexkit access token

# 8. Publish your app
apexkit liveapp publish
# Enter changelog when prompted
# Your app is now live!

# 9. Update and republish (anytime)
# Make changes to your code
apexkit liveapp publish
# Enter changelog for the update
# Updated version is deployed

Alternative: Manual Deployment

If you prefer manual deployment:

# Package your app
apexkit liveapp package

# Manually upload the zip file from output/ folder
# to your Apex Home Application Dashboard instance dashboard

Security Best Practices

Token Management

1. Never commit tokens to version control

   # Add to .gitignore
   echo ".apexkit/" >> .gitignore

2. Regenerate tokens periodically

   • Visit your Apex Home Application Dashboard developer dashboard
   • Generate a new token
   • Run apexkit login with the new token

3. Use environment-specific tokens

   • Development token for testing
   • Production token for live deployments

App Security

1. Validate all user inputs in your app.js
2. Never hardcode sensitive data - use config fields instead
3. Follow secure coding practices for API integrations
4. Keep dependencies updated with npm update

Development

Project Structure

apexkit/
├── index.js           # Main CLI script
├── package.json       # Package configuration
├── README.md          # This file
└── LICENSE            # ISC License

Building from Source

# Clone the repository
git clone https://github.com/yourusername/apexkit.git
cd apexkit

# Install dependencies (if any)
npm install

# Link locally for testing
npm link

# Test the CLI
apexkit liveapp create

Contributing

Contributions are welcome. Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the ISC License - see the LICENSE file for details.

Bug Reports

If you encounter any issues, please report them on the GitHub Issues page.

Support

• Email: [email protected]
• Discord: Join our community
• Documentation: docs.apexhome.io

Acknowledgments

• Built for the Apex Home Application Dashboard community
• Icons provided by Lucide Icons

Stats