ugcli User Guide

Tool Overview

The ugcli command-line tool provides project creation, packaging, configuration generation, and validation for UGOS Pro application developers. It runs on Windows, Linux, and macOS, helping developers quickly create and manage UGOS Pro application projects.

Download and Installation

Current version: 1.1.0.13

Download the executable for your operating system:

Platform	Architecture	File
Linux	x86_64	ugcli-linux-amd64
Windows	x86_64	ugcli-windows-amd64.exe
macOS	x86_64	ugcli-darwin-amd64

Linux/macOS Installation

Open a terminal and run (on macOS, use the ugcli-darwin-amd64 file):

# Add execute permission
chmod +x ugcli-linux-amd64

# Rename and move to system path
sudo mv ugcli-linux-amd64 /usr/local/bin/ugcli

# Verify installation
ugcli --version

Windows Installation

1. Download the corresponding .exe file
2. Rename it to ugcli.exe
3. Add the file path to the PATH environment variable
4. Run ugcli --version in a terminal to verify installation

Basic Commands

Create a New Project

Use the create subcommand to create a new application project with interactive prompts.

For example, to create a project named my-app:

$ugcli create my-app
Input new values for the config (press Enter to keep the current value):
? Set the application ID (e.g. com.mycompany.myapp)*: com.mycompany.myapp
? Set the version of your application (e.g. 1.0.0)*: 0.1.0
? Choose a type for your application*: utility
? Choose the architectures your application supports*: amd64, arm64
? Choose the open type for your application, inner: open in new window at desktop, tab: open in new tab at browser*: inner
? Enter the start command for your application's backend service (e.g. bin/myapp_server --port=28080)*: bin/myapp_serv --port=21010
? The port number that your application will listen on*: 21010
? The path that your application want system gateway to proxy to this port (leave empty if not needed): api
Configure your application's display information (en-US):
? Application display name*: My APP
? Application description*: My APP Desc
? Application author: nobody
? Application official website: https://myapp.example.com
? Application help website: https://myapp.example.com/help

Configuration notes:

• Application ID: Unique identifier in the format com.mycompany.myapp. Cannot be changed after publication.
• Version: Format x.y.z. The build number is appended during packaging as x.y.z.b (b is a 4-digit zero-padded build number, e.g. 0.1.0.0001). See Version Number Rules.
• Application Type: Category options: system (System Management), media (Entertainment), utility (Utilities), security (Security), download (Download), backup (Backup), devtool (Development Tools).
• Supported Architectures: amd64, arm64, multi-select.
• Client Types: Declared via supports in project.yaml: app (mobile), pc (desktop), tv (TV). Defaults to app, pc when omitted. See project.yaml Basic Configuration.
• Open Type: inner (desktop window) or tab (browser tab).
• Start Command: Backend service startup command with executable path relative to the installation directory.
• Listen Port: HTTP port for the backend service. Before startup, the system checks whether the port is in use; after startup, it probes the port to determine whether the application started successfully.
• Proxy Path: HTTP path prefix for gateway proxying to the backend. For example, if set to api/v1, all requests starting with /api/v1/ are forwarded to the backend.
• Display Information: Name, description, developer, official site, and help URL shown on the application detail page. Multi-language supported; English is configured by default. See Multi-language Configuration.

After completion, a my-app directory is generated with project.yaml and packaging directories.

$tree my-app
my-app
├── project.yaml      # Application configuration
├── rootfs_amd64      # Packaging directory (amd64)
├── rootfs_arm64      # Packaging directory (arm64)
└── rootfs_common     # Shared packaging directory
    ├── icon.png      # Application icon
    └── www           # Frontend static files

This is a typical frontend/backend separated application:

• Compile the backend for both architectures and place executables under rootfs_{amd64,arm64}/bin.
• Place built HTML, JS, and CSS under www. After installation, this directory is mapped to the system web server static resource path.
• After installation, the backend runs as a background service on the configured port. The frontend calls backend APIs; API requests are proxied by the system gateway.

If the application provides a complete web service on its own port and does not need static files from the system web server, set open_type to tab. Users can then access the application directly via IP and port in a new browser tab.

Edit Project Configuration

Use the config subcommand to view and edit project configuration.

# Enter the project directory
$cd my-app

# View current project configuration
$ugcli config list

# Edit project configuration (interactive); press Enter to keep current values
$ugcli config edit

# Add or edit display information for a specific language (interactive)
$ugcli config edit i18n
? Choose a language to edit: zh-CN
Input new values for the config (press Enter to keep the current value):
Configure your application's display information (zh-CN):
? Application display name*: Demo App (MY APP)
? Application description*: Demo app description
? Application author: Demo developer
? Application official website:
? Application help website:

Multi-language Configuration

Edit the i18n field in project.yaml:

i18n:
  en-US:
    name: My APP
    description: My APP Desc
    author: My Company
    official: https://myapp.example.com
    help: https://myapp.example.com/help
    publisher: My Company
    publisher_link: https://mycompany.example.com
  zh-CN:
    name: 演示应用
    description: 演示应用描述
    author: 演示应用开发者
    official: https://myapp.example.com.cn
    help: https://myapp.example.com.cn/help
    publisher: 演示应用发布者
    publisher_link: https://mycompany.example.com.cn

Field descriptions:

• name: Display name
• description: Description shown on the detail page
• author: Developer
• official (optional): Official website
• help (optional): Help documentation URL
• publisher (optional): Publisher name
• publisher_link (optional): Publisher website

Supported locale codes:

en-US
zh-CN
de-DE
ja-JP
fr-FR
nl-NL
pt-PT
es-ES
it-IT
ko-KR
zh-TW

Language configuration notes:

• If no content exists for the user's current system language, the App Center detail page defaults to English (en-US).
• Keep en-US as the fallback language. When listing in specific regions only, provide English in addition to the target locale; when users switch language, English is used when no matching locale is configured.
• In-app UI internationalization is the developer's responsibility. See project.yaml Language Configuration.

Compliance and support links can also be configured at the root level of project.yaml (see Application Links and Compliance Information):

• privacy_policy_link: Privacy policy URL(s)
• license_agreement_link: License agreement URL(s) (required when the application uses open-source code)
• source_code_link: Source code URL(s) (required when the application uses open-source code)
• technical_support_link: Technical support URL(s)

Check Project Configuration

Use the check subcommand to validate project configuration.

$ugcli check
Checking project in /home/example/my-app
✓ check passed

This checks:

• project.yaml and its contents
• rootfs directory structure

Package Project

Use the pack subcommand to package the project into an upk installation package. The package includes all files under rootfs_common and rootfs_{arch} (with rootfs_{arch} taking precedence for same-name files), plus project configuration.

# Package the current project
ugcli pack --arch all --build 1

Parameters:

• --build, -b: Build number (integer). Combined with version (x.y.z) in project.yaml to produce final version x.y.z.b (e.g. 0.1.0.0001).
• --arch, -a: Target architecture (amd64/arm64/all)

Run ugcli pack --help for more options.

Version and Build Number

• Set version: x.y.z in project.yaml.
• Specify the build number via --build during packaging. Final version is x.y.z.b (b is a 4-digit zero-padded build number).
• Under the same x.y.z, each new submission must use an incremented build number. Duplicates are not allowed.
• Higher version numbers indicate newer releases. See Version Number Rules.

Example:

# project.yaml: version: 0.1.0
ugcli pack --build 1    # 0.1.0.0001
ugcli pack --build 2    # 0.1.0.0002

After packaging, an upk file is generated under build_dir/pkgs/upk with the naming format {arch}_{appid}_{version}.upk. Here {version} is the full version x.y.z.b (e.g. 0.1.0.0001).

FAQ

How to install and test a packaged upk file

1. Prepare a UGREEN NAS device running the latest UGOS Pro firmware.
2. Submit the device serial number, MAC address, and admin username to UGREEN to apply for developer authorization.
3. Rename the authorization file to ugdev.sig and upload it to the admin user's Personal Folder.
4. Open App Center on the NAS, choose manual installation, and select the upk file for testing.