📚 Table of Contents

• Installation
• Quick Start
• App Management
• Asset Management
  • Services
  • Weblets
  • Resources
• Platform Management
• Synchronization
• Configuration Files
• Debugging
• Bundle Management
• Snapshot Management

🚀 Installation

1. Install Node.JS
2. Install the CLI globally:

   npm install -g zeysdk2

💫 Quick Start

1. Create your first app:

   zeysdk create my-app --name="My First App"

2. Link to your ZeyOS instance:

   zeysdk link myinstance

3. Add your first asset:

   zeysdk add weblets/dashboard.js --name="Dashboard" --type=integrated

4. Start development with auto-sync:

   zeysdk watch

📦 App Management

Creating Applications

zeysdk create <IDENTIFIER> --name=<NAME>

Creates a new ZeyOS application with the following structure:

my-app/
├── .zeysdk/                    # Sync and instance configuration
│   └── sync.json              # Tracks file states for sync
├── assets/                     # Generic assets (supports nested structure)
├── resources/                  # Static assets (.ixml files)
├── services/                   # Background tasks (.ixml files)
├── settings/                   # App configuration
│   ├── defaultsettings.json   # Default application settings
│   ├── settingscode.ixml      # Settings initialization code
│   └── usersettingscode.ixml  # User settings code
├── weblets/                    # UI components (.ixml files)
├── README.md                   # Application documentation
└── zeyos.app.json              # App manifest

Application Options

| Option | Description | Required | Example | |--------|-------------|----------|---------| | IDENTIFIER | Unique app ID | ✅ | my-app | | --name | Display name | ✅ | "My App" | | --description | App description | ❌ | "Tool for..." | | --vendor | Vendor name | ❌ | "ACME Inc" | | --version | Version number | ❌ | 10000 |

🎨 Asset Management

The SDK supports four types of asset folders:

• Assets - Generic assets with nested folder support (e.g., assets/images/logo.png)
• Resources - Static files (.ixml format)
• Services - Background tasks (.ixml format)
• Weblets - UI components (.ixml format)

Common Asset Commands

# Add an asset (iXML files)
zeysdk add <ASSET_CLASS>/<FILENAME>
Example: zeysdk add services/test.ixml

# Add generic asset (supports nested paths)
zeysdk add assets/<PATH>/<FILENAME>
Example: zeysdk add assets/images/logo.png

# Update asset properties (for services/weblets/resources)
zeysdk update <ASSET_CLASS>/<FILENAME>
Example: zeysdk update services/test.ixml --type=after_creation --entity=contacts

# Remove an asset (deletes file, removes from zeyos.app.json and sync.json)
zeysdk remove <ASSET_CLASS>/<FILENAME>
Example: zeysdk remove services/test.ixml
Example: zeysdk remove assets/images/logo.png
Note: Automatically cleans up empty parent directories

# Rename an asset
zeysdk rename <ASSET_CLASS>/<OLD_FILENAME> <ASSET_CLASS>/<NEW_FILENAME>
Example: zeysdk rename services/old.ixml services/new.ixml
Example: zeysdk rename assets/old-logo.png assets/new-logo.png

Note: When updating an asset and changing its type, obsolete properties will be automatically removed from the configuration (zeyos.app.json).

1. Services (Background Tasks)

Basic Usage

zeysdk add services/sendreminder.ixml \
  --name="Send reminders" \
  --type=timing \
  --schedule=600 \
  --interval=60

Service Configuration Options

| Option | Description | Required | Example | |--------|-------------|----------|---------| | name | Service name | ✅ | "Send reminders" | | type | Service type (see below) | ✅ | "timing" | | schedule | Start time in minutes since midnight | For timing | 990 (16:30 = 16.5 * 60) | | interval | Execution interval in minutes | For timing | 60 (hourly) | | entity | ZeyOS entity class | For hooks | "contacts" | | accesskey | Security key for remote calls | For remotecall | "secret-key" | | url | External service URL | Optional | "https://api.example.com" |

Service Types

1. Scheduled Services (timing)

   • Required: schedule (minute of day), interval (minutes)

   zeysdk add services/backup.ixml \
     --name="Daily Backup" \
     --type=timing \
     --schedule=990 \  # 16:30 (16.5 * 60)
     --interval=1440   # Daily

2. Remote Services (remotecall)

   • Optional: accesskey, url

   zeysdk add services/api.ixml \
     --name="External API" \
     --type=remotecall \
     --url="https://api.example.com" \
     --accesskey="secret"

3. Entity Hooks

   • All require entity property
   • Types and triggers:
     • after_creation: After object creation
     • before_modification: Before object update
     • after_modification: After object update
     • after_creation_modification: After create/update
     • before_deletion: Before object deletion
     • after_deletion: After object deletion

   zeysdk add services/contact-hook.ixml \
     --name="Contact Monitor" \
     --type=after_creation \
     --entity=contacts

For available entity options, see List of ZeyOS Entities.

2. Weblets (UI Components)

Weblets define the user interface elements of your application.

Basic Usage

zeysdk add weblets/picklist.ixml \
  --name="Picking List" \
  --type=detached \
  --view=billing.details_transaction

Weblet Configuration Options

| Option | Description | Required | Example | |--------|-------------|----------|---------| | name | Weblet display name | ✅ | "Picking List" | | type | Weblet type | ✅ | "popup_framed" | | view | ZeyOS view to expand | ✅ | "billing.details_transaction" | | width | Popup width (pixels) | For popups | 800 | | height | Popup height (pixels) | For popups | 600 | | langaliases | Language translations | ❌ | {"de_DE": "Pickliste"} | | url | External weblet URL | Optional | "https://app.example.com" |

For available view options, see List of ZeyOS Views.

Weblet Types

1. Menu Integration

   • integrated: Appears below ZeyOS menu bar

   zeysdk add weblets/menu.ixml \
     --name="Main Menu" \
     --type=integrated \
     --view=main.index

2. Popups (require width and height)

   • popup_framed: Modal with title bar
   • popup_plain: Plain modal without title

   zeysdk add weblets/dialog.ixml \
     --name="Settings" \
     --type=popup_framed \
     --width=800 \
     --height=600 \
     --view=settings.main

3. Standalone Windows

   • standalone: Independent window in ZeyOS UI
   • detached: Opens in new browser tab/window

   zeysdk add weblets/external.ixml \
     --name="External Tool" \
     --type=detached \
     --view=links.index

4. Embedded Components

   • embedded_framed: Panel with frame
   • embedded_collapsed: Collapsible panel
   • embedded_plain: Plain iframe without panel

   zeysdk add weblets/panel.ixml \
     --name="Info Panel" \
     --type=embedded_framed \
     --view=inventory.index

3. Resources (Static Assets)

Resources are static files like images, stylesheets, or other content.

Basic Usage

zeysdk add resources/logo.png \
  --name="Company Logo" \
  --public=1

Resource Configuration Options

| Option | Description | Required | Default | |--------|-------------|----------|---------| | name | Resource name | ✅ | - | | public | Public accessibility | ❌ | 0 |

4. Assets (Generic Files)

The assets/ folder supports generic files with nested directory structures, making it ideal for organized file storage.

Basic Usage

# Add a simple asset
zeysdk add assets/logo.png

# Add a nested asset
zeysdk add assets/images/icons/favicon.ico

# Add text files
zeysdk add assets/data/config.json

Features

• ✅ Nested folders - Organize files in subdirectories (e.g., assets/images/logos/)
• ✅ Any file type - Images, JSON, text, binary files, etc.
• ✅ Automatic sync - Tracked in sync.json for conflict detection
• ✅ Empty files - Supports zero-byte files

Asset Configuration Options

| Option | Description | Required | Default | |--------|-------------|----------|---------| | mimetype | File MIME type | ❌ | Auto-detected |

Note: Unlike resources/services/weblets, assets don't require a --name parameter and support nested paths.

Configuration Examples

1. Update Service Type:

# Change from timing to entity hook
zeysdk update services/reminder.ixml \
  --type=after_creation \
  --entity=contacts

# Previous timing properties (schedule, interval) will be automatically removed

2. Multi-language Weblet:

zeysdk add weblets/dashboard.ixml \
  --name="Dashboard" \
  --type=integrated \
  --view=main.index \
  --langaliases='{"de_DE":"Dashboard","es_ES":"Panel"}'

3. Public Resource:

zeysdk add resources/style.css \
  --name="Public Stylesheet" \
  --public=1

4. Nested Asset:

zeysdk add assets/images/icons/favicon.ico

🔗 Platform Management

Connect and manage ZeyOS instances:

# Link to instance
zeysdk link myinstance [--url=https://custom.url]

Link Options

| Option | Description | Required | Default |
|--------|-------------|----------|---------|
| `--url` | Instance URL | ❌ | `https://cloud.zeyos.com/<myinstance>
| `--token` | Auth token | ❌ | Prompted if not provided |
| `--verbose` | Detailed output | ❌ | `false` |

# Switch between instances
zeysdk use myinstance

# View current instance
zeysdk whoami

# List all instances
zeysdk hosts

# Remove instance
zeysdk unlink myinstance

Default URL pattern: https://cloud.zeyos.com/<INSTANCE_ID>/

🔍 Debugging

Runs a given iXML or Zymba script in the platform's console. This means that the code is not executed locally on your machine, but runs on your ZeyOS development machine.

zeysdk run <ASSET_CLASS>/<FILENAME>

Supported script types:

• iXML scripts
• Zymba scripts

The code runs on the ZeyOS platform, not locally.

📦 Bundle Management

Install multiple applications from a bundle file to a specified instance.

# Create bundle
zeysdk generate-bundle [output]

# Install bundle
zeysdk install <bundle> <instance>

Bundle Options

| Option | Description | Default | |--------|-------------|---------| | output | Bundle filename | Interactive prompt | | --verbose | Show details | false | | --force | Skip confirmation | false |

📸 Snapshot Management

# Create snapshot
zeysdk snapshot "Initial setup"

# List snapshots
zeysdk snapshots

# Restore snapshot
zeysdk restore <snapshot-id>

# Remove snapshot
zeysdk drop <snapshot-id>

Snapshot Options

| Option | Description | Default | |--------|-------------|---------| | --dir | Target directory | Current directory | | --force | Skip confirmation | false |

🔄 Synchronization

When you work on your application, you will require a ZeyOS platform as testing and development environment. For this purpose, you will need to link your application with a ZeyOS instance. Since you might want to deploy your application on multiple instances, you can also specify an instance ID in order to switch between instances via zeysdk use.

Every time you create a new instance, a new instance configuration is created in .zeysdk/sync.<instanceid>.json. The currently active instance configuration is stored in .zeysdk/sync.json.

Basic Commands

# Compare changes
zeysdk compare [files...]

# Two-way sync
zeysdk sync [files...]

# Upload changes
zeysdk push [files...]

# Download changes
zeysdk pull [files...]

# Auto-sync during development
zeysdk watch

* `compare`: Only compares the client side with the server side. No changes will be transferred
* `sync`: New files will replace old files on both sides - local and remote.
* `push`: Push local changes to the server - server changes will be overwritten
* `pull`: Pull changes from the server - local changes will be overwritten
* `watch`: Watches changes on client side and pushes changes to server side.
    - server changes will be overwritten

⚙️ Configuration Files

When using the SDK, you will notice that a couple of configuration files are being created:

1. Application Manifest (zeyos.app.json)

Describes the application's properties and represents the properties of all included assets

{
  "identifier": "myapp",
  "name": "My Application",
  "version": 10000,
  "vendor": "Company Name",
  "assets": {
    "images/logo": {
      "mimetype": "image/png"
    }
  },
  "resources": {
    "logo": {
      "mimetype": "image/png",
      "public": 1
    }
  },
  "services": {
    "reminder": {
      "type": "timing",
      "schedule": 600,
      "interval": 60
    }
  },
  "weblets": {
    "dashboard": {
      "type": "popup_framed",
      "width": 800,
      "height": 600
    }
  }
}

2. The ZeyOS Sync File (sync.json)

The sync.json file is created whenever you are syncing an application with a ZeyOS instance.

The instance configuration stores the authentication information when executing zeysdk link <instanceid>. By using zeysdk use <instanceid> a user can switch between different instances.

Example:

{
  "id": "instance-id",
  "url": "platform-url",
  "syncstates": {
    "settings": {
      "hash": "file-hash",
      "lastmodified": "timestamp"
    },
    "defaultsettings": {
      "hash": "file-hash",
      "lastmodified": "timestamp"
    },
    "services": {},
    "weblets": {},
    "resources": {},
    "assets": {}
  }
}

The sync configuration consists of two core sections:

{
  "id": "instance-id",
  "url": "https://platform-url"
}

• Updated automatically when running zeysdk link
• Contains platform URL
• Manages instance connection details

{
  "syncstates": {
    "settings": {
      "hash": "file-hash",
      "lastmodified": 1234567890
    },
    "resources": {},
    "services": {},
    "weblets": {}
  }
}

• Tracks file states for settings, resources, services, and weblets
• Uses lastmodified timestamp and hash for change detection
• Manages synchronization between local and server files

Sync Scenarios

When lastmodified and hash are empty:

| Scenario | Action | Resolution Options | |----------|--------|-------------------| | File doesn't exist on server | Auto-create | N/A | | File exists on server | Conflict | • theirs: Use server version• mine: Use local version |

When lastmodified and hash exist:

| Scenario | Action | Resolution Options | |----------|--------|-------------------| | File missing on server | Conflict | • theirs: Remove locally• mine: Create on server | | States don't match | Conflict | • theirs: Use server version• mine: Use local version | | States match | Auto-sync | Copy to server |

We highly recommend using the SDK's interface to edit those file and restrain from editing them directly.

However, in some cases you might want to automate certain tasks through additional scripts and task runners - in such cases it is certainly useful to have a better understanding about the underlying file structure and properties.

BE CAREFUL WHEN MANIPULATING THE SYNC STATES, YOU ARE PUTTING YOUR SYSTEM INTEGRITY AT RISK!

📚 Documentation

• Run zeysdk help
• Visit docs.zeyos.com
• Check List of ZeyOS Entities
• See List of ZeyOS Views

📄 License

MIT License - see LICENSE file for details.