ugcli User Guide

Tool Introduction

ugcli is a command-line tool designed to provide UGOS Pro system application developers with features such as project creation, packaging, configuration generation, and checking. This tool supports running on Windows, Linux, and macOS systems, helping developers quickly create and manage UGOS Pro application projects.

Download and Installation

Download the corresponding executable file based on your operating system:

Platform	Architecture	File Name
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 on your system and execute the following shell commands (use ugcli-darwin-amd64 for macOS):

# 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 the file to ugcli.exe
3. Add the file path to the PATH environment variable
4. Run ugcli --version in the terminal to verify installation

Basic Command Usage

Create a New Project

Use the create subcommand to create a new application project and configure the basic information of the application through interactive Q&A.

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 item descriptions:

• Application ID: The unique identifier of the application, in the format com.mycompany.myapp, used by the system to identify the application. Cannot be modified after the application is published.
• Version Number: The version number of the application, in the format x.y.z.
• Application Type: The category of the application. Options: system (System Management), utility (Utility), media (Entertainment), security (Security), download (Download), backup (Backup & Sync), devtool (Development Tools).
• Supported Architectures: The CPU architectures supported by the application. Options: amd64, arm64. Multiple selections are supported.
• Open Type: How to open the application interface after installation. Options: inner (opens as an independent window within the system desktop), tab (opens in a new browser tab).
• Startup Command: The startup command for the application backend service, including the backend service executable path (relative to the application installation directory) and command-line arguments.
• Listen Port: The port number that the application backend service listens on for providing HTTP service. Before the application starts, the system checks whether this port is occupied. After startup, the system detects this port to determine whether the application has started successfully.
• Proxy Path: The HTTP request path prefix that the application needs the system gateway to proxy, used to forward frontend requests to the backend service. For example, if set to api/v1, all requests starting with /api/v1/ will be forwarded to the backend service.
• Application Display Information: Information displayed on the application detail page, including application name, detailed description, developer, official website, and support link. Multiple languages are supported. The default configured language is English. To add other language configurations, please refer to Multi-language Configuration.

After completing the configuration as prompted, a my-app directory will be generated in the current directory, containing the application configuration file project.yaml and directories needed for packaging.

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

The application is a typical frontend-backend separated application:

• The backend service program needs to be compiled into versions for both architectures, placed in the corresponding architecture rootfs_{amd64,arm64}/bin directories.
• Frontend-built static files such as HTML, JS, CSS are placed in the www directory. This directory will be mapped to the system web server's static resource directory after the application is installed, and will be directly served by the system web server.
• After the application is installed and enabled, the backend service program will run as a background service listening on the specified port. The frontend interacts with it through API calls to the backend service. API requests will be proxied and forwarded by the system gateway to the backend service.

If the application's own listening port provides complete web service and does not need the system web server to provide static resource access, the open type can be configured as tab. When the user clicks the desktop application icon, it will open directly in a new browser tab via IP+port to access the application.

Modify Project Configuration

Use the config subcommand to view and modify project configuration.

# Enter project directory
$cd my-app

# View current project configuration
$ugcli config list

# Modify project configuration (interactive), press Enter to keep unchanged
$ugcli config edit

# Add or modify application description information for a specified 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*: 演示应用(MY APP)
? Application description*: 演示应用描述
? Application author: 演示应用开发者
? Application official website:
? Application help website:

Multi-language Configuration

You can directly modify the i18n field in the project.yaml file to configure multi-language information, for example:

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: Application display name
• description: Application description, displayed on the application detail page
• author (optional): Application developer
• official (optional): Application official website link
• help (optional): Support link
• publisher (optional): Application publisher
• publisher_link (optional): Application publisher website link

Configurable language list:

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

Check Project Configuration

Use the check subcommand to verify whether the project configuration is correct.

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

This will check the completeness of the project configuration, including:

• project.yaml configuration file and its contents
• rootfs directory structure

Package the Project

Use the pack subcommand to package the project into a upk format installation package. The installation package will contain all files in the project's rootfs_common and rootfs_{arch} directories (files with the same name will use rootfs_{arch} as the priority), as well as the project's configuration information.

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

Parameter descriptions:

• --build, -b: Set the build number (integer)
• --arch, -a: Specify target architecture (options: amd64/arm64/all)

For more parameters and usage instructions, run ugcli pack --help to view detailed help information.

After packaging is complete, a upk format installation package will be generated in the project's build_dir/pkgs/upk directory, with the file name {arch}_{appid}_{version}.{build}.upk.

FAQ

How to Install and Test the Packaged upk File

1. Prepare a UGREEN NAS device and upgrade to the latest version of the UGOS Pro system.
2. Submit the NAS device's serial number, MAC address, and administrator username to UGREEN officially to apply for developer authorization.
3. Rename the authorization file to ugdev.sig and upload it to the admin's Personal Folder on the NAS device.
4. Open the "App Center" on the NAS device, click "Manual Install", and select the packaged upk file for installation testing.