HoloCubic CLI is a community companion project for the two upstream HoloCubic repositories above. It does not replace the firmware or app collection; it makes their DevTools workflow scriptable from Windows, Linux, and macOS.

HoloCubic CLI provides three stable, cross-platform command-line clients for the HoloCubic DevTools HTTP API. Choose the runtime you already use; all three implementations expose the same device, SD-card, DevRun, and app workflows.

All three packages are released as version 0.1.0.

Install one implementation. You do not need all three.

npm install --global @princival/holocubic-cli
cubic --version

python -m pip install holocubic-cli-python
cubic-py --version

With uv, the CLI can be installed as an isolated tool:

uv tool install holocubic-cli-python
cubic-py --version

cargo install holocubic-cli-rust --version 0.1.0 --locked
cubic-rs --version

The examples use cubic. Substitute cubic-py or cubic-rs when using the Python or Rust package.

cubic device add desk 192.168.3.26
cubic ping
cubic info
cubic ls /sd/apps
cubic push ./my-app /sd/apps/my-app
cubic pull /sd/apps/my-app ./my-app-backup

One-off access does not change saved configuration:

cubic --host 192.168.3.26 --json info

Target resolution order is --host, CUBIC_HOST, then the selected saved device. CUBIC_CONFIG can isolate the configuration file in scripts and CI.

• Developers can manage SD-card files and apps directly from a terminal, automate repeated deployment steps, and keep device profiles locally.
• Scripts and CI can select a device explicitly, isolate configuration with CUBIC_CONFIG, consume --json output, and rely on meaningful exit codes.
• AI agents can install any of the three packages and invoke the CLI as a controlled subprocess instead of reproducing the DevTools HTTP protocol.

A machine-friendly session can begin with read-only discovery:

cubic --host 192.168.3.26 --json ping
cubic --host 192.168.3.26 --json info
cubic --host 192.168.3.26 --json ls /sd/apps

Agents should prefer explicit hosts and JSON output, inspect before mutating, and preserve the CLI's --force, --recursive, and --yes safeguards.

All implementations support the same command surface:

device add|list|use|remove
ping
info
ls [remote]
stat <remote>
cat <remote>
mkdir <remote>
mv <source> <target>
rm [-r --yes] <remote>
push|upload <local> [remote]
pull|download <remote> [local]
devrun read|save|run
app list|install|remove

Directory transfers preserve empty directories and arbitrary binary data. They enforce depth, entry-count, and download-size limits, reject symbolic links, and commit through temporary siblings. Existing targets require --force; recursive deletion requires --recursive --yes.

git clone https://github.com/Tim-1e/holocubic-cli.git
cd holocubic-cli

Then use the development instructions in the relevant implementation README:

• Node.js
• Python
• Rust

The device API is documented in spec/api-v1.md, and shared CLI behavior is defined in spec/cli-v1.md.

The conformance gate covers saved devices, recursive binary and empty-folder round trips, rename/delete safeguards, DevRun, app workflows, JSON output, and exit codes. Maintainer release procedures are documented in docs/RELEASING.md.

If this companion makes your HoloCubic workflow easier, please use it, share it with other HoloCubic users, and give the repository a ⭐. Issues and focused pull requests are welcome.

Released under the MIT License.

English | 简体中文

This repository contains example Lua apps that can run directly from the device's SD card. The package/ directory of each app is its deployment package. Copy it to /sd/apps/<app-id>/ on the device, then rescan apps in Launcher to make it available.

See README_LUA.md for the underlying Lua module APIs and README_LVGL.md for the LVGL UI bindings. This document focuses on the project structure, common API entry points, and debugging workflow most useful for DIY apps.

A typical app directory looks like this:

my_app/
└── package/
    ├── app.info              # App metadata; required
    ├── main.lua              # Entry script; required; filename is set by entry in app.info
    ├── main.png              # App icon; recommended
    ├── info.html             # Description page shown in Launcher; recommended
    ├── font/                 # Font resources; optional
    ├── assets/               # Images, GIFs, audio, and other assets; optional
    └── modules/              # .so extension modules; optional

After deploying package/, the files are normally located at:

/sd/apps/my_app/app.info
/sd/apps/my_app/main.lua
/sd/apps/my_app/main.png

app.info is a simple key = value text file. Common fields are:

Minimal regular app:

name = Hello
name_zh = 示例
name_zh_cn = 示例
name_zh_tw = 範例
name_zh_hant = 範例
name_en = Hello
name_ja = サンプル
kind = app
category = tool
catalog_scope = community
entry = main.lua
icon = main.png
description = Minimal DIY app
description_zh = 最小 DIY 应用示例
description_zh_cn = 最小 DIY 应用示例
description_zh_tw = 最小 DIY 應用程式範例
description_zh_hant = 最小 DIY 應用程式範例
description_en = Minimal DIY app
description_ja = 最小構成の DIY アプリ例
version = 0.1.0

For an auto-start service app, refer to devtools/package/app.info:

name = DevTools
name_zh_cn = 开发工具
name_zh_tw = 開發工具
name_en = DevTools
name_ja = 開発ツール
kind = service
category = tool
catalog_scope = official
entry = main.lua
allow_webui = true
autostart_service = true
description = Developer tools service
description_zh = 开发工具服务
description_zh_tw = 開發工具服務
description_en = Developer tools service
description_ja = 開発ツールサービス
version = 0.0.0

These are the APIs most commonly used by regular apps:

Example:

key.on(key.HOME, function(evt_type)
  if evt_type == key.SHORT then
    app.exit()
  end
end)

Use explicit /sd/... paths, for example /sd/apps/hello/config.json.

Lua code uses the global lv_* functions and LV_* constants directly. Common entry points are:

See README_LVGL.md for more widgets, including button, table, list, tabview, chart, GIF, and canvas APIs.

HTTP request example:

http.get("https://example.com/", {}, function(code, body, headers)
  print("status", code)
  print(body or "")
end)

Create hello/package/app.info:

name = Hello
name_zh_cn = 示例
name_zh_tw = 範例
name_en = Hello
name_ja = サンプル
kind = app
category = tool
catalog_scope = community
entry = main.lua
icon = main.png
description = Minimal DIY app
description_zh = 最小 DIY 应用示例
description_zh_tw = 最小 DIY 應用程式範例
description_en = Minimal DIY app
description_ja = 最小構成の DIY アプリ例
version = 0.1.0

Create hello/package/main.lua:

local APP_KEY = "APP_HELLO"

local prev = rawget(_G, APP_KEY)
if prev and prev.stop then
  pcall(function()
    prev.stop("reload")
  end)
end

local APP = {
  tick = 0,
  timer = nil
}
_G[APP_KEY] = APP

local root = lv_scr_act()
lv_obj_clean(root)

local MAIN = LV_PART_MAIN | LV_STATE_DEFAULT

lv_obj_set_style_bg_color(root, 0x101820, MAIN)
lv_obj_set_style_bg_opa(root, 255, MAIN)

local title = lv_label_create(root)
lv_label_set_text(title, "Hello DIY App")
lv_obj_set_style_text_color(title, 0xFFFFFF, MAIN)
lv_obj_set_style_text_font(title, LV_FONT_MONTSERRAT_20, MAIN)
lv_obj_align(title, LV_ALIGN_CENTER, 0, -20)

local sub = lv_label_create(root)
lv_label_set_text(sub, "tick: 0")
lv_obj_set_style_text_color(sub, 0x8FD6FF, MAIN)
lv_obj_set_style_text_font(sub, LV_FONT_MONTSERRAT_16, MAIN)
lv_obj_align(sub, LV_ALIGN_CENTER, 0, 18)

APP.timer = tmr.create()
APP.timer:alarm(1000, tmr.ALARM_AUTO, function()
  APP.tick = APP.tick + 1
  lv_label_set_text(sub, "tick: " .. tostring(APP.tick))
end)

key.on(key.HOME, function(evt_type)
  if evt_type == key.SHORT then
    app.exit()
  end
end)

function APP.stop(reason)
  if APP.timer then
    pcall(function() APP.timer:stop() end)
    pcall(function() APP.timer:unregister() end)
    APP.timer = nil
  end

  pcall(function() key.off() end)

  if lv_obj_clean then
    pcall(function() lv_obj_clean(root) end)
  end

  if rawget(_G, APP_KEY) == APP then
    _G[APP_KEY] = nil
  end
end

APP.shutdown = APP.stop

After deployment, the directory should look like this:

/sd/apps/hello/app.info
/sd/apps/hello/main.lua
/sd/apps/hello/main.png

Then rescan apps in Launcher. In the current Launcher, a short press on DOWN calls app.rescan(). You can also restart the device or call app.rescan() from your own script.

After the device connects to Wi-Fi, use one of the following methods to find its IP address:

• Open the Settings app and view the Wi-Fi/IP information.
• Print it from Lua:

local ip, netmask, gateway = wifi.sta.getip()
print("device ip:", ip, netmask, gateway)

• Register a network connection event:

wifi.sta.on("got_ip", function(_, info)
  print("ip:", info.ip)
end)

The computer and the device must be on the same LAN. If the device IP is 192.168.0.140, open the following URL in a browser:

http://192.168.0.140/devtools/

devtools/package is an auto-start service with the fixed /devtools/ entry point. The compatibility route /codeeditor/ redirects to /devtools/.

Main features:

DevRun is suitable for quickly testing code. Once the code is ready, organize it into a separate app directory with its own app.info.

Base prefix: /devtools/api

Examples:

curl "http://192.168.0.140/devtools/api/list?path=/sd/apps"

curl -X POST \
  --data-binary @hello/package/main.lua \
  "http://192.168.0.140/devtools/api/code/run"

DevTools uploads use the firmware-native PUT /api/system/fs/upload?path=... endpoint directly. Read APIs still return data in chunks, while browser downloads use file streaming; none of these paths load a complete file into Lua memory. The legacy /devtools/api/upload endpoint remains available for existing clients, but it passes request bodies through Lua and is slower than the firmware-native endpoint. The maximum size of a single file is 64 MB.

When upgrading for the first time from an old version without /reload, restart the device once. After that, use App update at the top of the page.

To upload a complete app, first create /sd/apps/hello from the DevTools page, then upload app.info, main.lua, main.png, and other files. Finally, rescan the app list.

• Release resources before exit or reload: timer:unregister(), key.off(), and app.on(name, nil).
• Do not block for long periods inside callbacks. Use tmr for periodic work and check app.exiting() inside long-running loops.
• After deployment, UI asset paths should use /sd/apps/<app-id>/....
• After loading a font with lv_font_load(), release it with lv_font_free() when the app exits.
• Handle network and file I/O failures using the value | nil, err convention.
• info.html is the description page embedded in Launcher. See info页面要求.md for generation requirements.

English | 简体中文

这个仓库是一组可直接放到设备 SD 卡运行的 Lua app 示例。每个 app 的 package/ 目录就是部署包，通常复制到设备的 /sd/apps/<app-id>/ 后，launcher 重扫即可显示。

底层 Lua 模块接口见 README_LUA.md，LVGL UI 绑定见 README_LVGL.md。本文只写 DIY app 最常用的结构、接口入口和调试方式。

常见 app 目录：

my_app/
└── package/
    ├── app.info              # app 元信息，必须
    ├── main.lua              # 入口脚本，必须，文件名由 app.info 的 entry 指定
    ├── main.png              # 图标，推荐
    ├── info.html             # launcher 内展示的介绍页，推荐
    ├── font/                 # 字体资源，可选
    ├── assets/               # 图片、GIF、音频等资源，可选
    └── modules/              # .so 扩展模块，可选

package/ 部署到设备后路径一般是：

/sd/apps/my_app/app.info
/sd/apps/my_app/main.lua
/sd/apps/my_app/main.png

app.info 是简单的 key = value 文本。常用字段：

最小普通 app：

name = Hello
name_zh = 示例
name_zh_cn = 示例
name_zh_tw = 範例
name_zh_hant = 範例
name_en = Hello
name_ja = サンプル
kind = app
category = tool
catalog_scope = community
entry = main.lua
icon = main.png
description = Minimal DIY app
description_zh = 最小 DIY 应用示例
description_zh_cn = 最小 DIY 应用示例
description_zh_tw = 最小 DIY 應用程式範例
description_zh_hant = 最小 DIY 應用程式範例
description_en = Minimal DIY app
description_ja = 最小構成の DIY アプリ例
version = 0.1.0

自启动服务 app 可参考 devtools/package/app.info：

name = DevTools
name_zh_cn = 开发工具
name_zh_tw = 開發工具
name_en = DevTools
name_ja = 開発ツール
kind = service
category = tool
catalog_scope = official
entry = main.lua
allow_webui = true
autostart_service = true
description = Developer tools service
description_zh = 开发工具服务
description_zh_tw = 開發工具服務
description_en = Developer tools service
description_ja = 開発ツールサービス
version = 0.0.0

普通 app 最常用：

示例：

key.on(key.HOME, function(evt_type)
  if evt_type == key.SHORT then
    app.exit()
  end
end)

路径建议显式写 /sd/...，例如 /sd/apps/hello/config.json。

Lua 里直接使用全局 lv_* 函数和 LV_* 常量。常用入口：

更多控件如 button、table、list、tabview、chart、gif、canvas 见 README_LVGL.md。

HTTP 请求示例：

http.get("https://example.com/", {}, function(code, body, headers)
  print("status", code)
  print(body or "")
end)

新建 hello/package/app.info：

name = Hello
name_zh_cn = 示例
name_zh_tw = 範例
name_en = Hello
name_ja = サンプル
kind = app
category = tool
catalog_scope = community
entry = main.lua
icon = main.png
description = Minimal DIY app
description_zh = 最小 DIY 应用示例
description_zh_tw = 最小 DIY 應用程式範例
description_en = Minimal DIY app
description_ja = 最小構成の DIY アプリ例
version = 0.1.0

新建 hello/package/main.lua：

local APP_KEY = "APP_HELLO"

local prev = rawget(_G, APP_KEY)
if prev and prev.stop then
  pcall(function()
    prev.stop("reload")
  end)
end

local APP = {
  tick = 0,
  timer = nil
}
_G[APP_KEY] = APP

local root = lv_scr_act()
lv_obj_clean(root)

local MAIN = LV_PART_MAIN | LV_STATE_DEFAULT

lv_obj_set_style_bg_color(root, 0x101820, MAIN)
lv_obj_set_style_bg_opa(root, 255, MAIN)

local title = lv_label_create(root)
lv_label_set_text(title, "Hello DIY App")
lv_obj_set_style_text_color(title, 0xFFFFFF, MAIN)
lv_obj_set_style_text_font(title, LV_FONT_MONTSERRAT_20, MAIN)
lv_obj_align(title, LV_ALIGN_CENTER, 0, -20)

local sub = lv_label_create(root)
lv_label_set_text(sub, "tick: 0")
lv_obj_set_style_text_color(sub, 0x8FD6FF, MAIN)
lv_obj_set_style_text_font(sub, LV_FONT_MONTSERRAT_16, MAIN)
lv_obj_align(sub, LV_ALIGN_CENTER, 0, 18)

APP.timer = tmr.create()
APP.timer:alarm(1000, tmr.ALARM_AUTO, function()
  APP.tick = APP.tick + 1
  lv_label_set_text(sub, "tick: " .. tostring(APP.tick))
end)

key.on(key.HOME, function(evt_type)
  if evt_type == key.SHORT then
    app.exit()
  end
end)

function APP.stop(reason)
  if APP.timer then
    pcall(function() APP.timer:stop() end)
    pcall(function() APP.timer:unregister() end)
    APP.timer = nil
  end

  pcall(function() key.off() end)

  if lv_obj_clean then
    pcall(function() lv_obj_clean(root) end)
  end

  if rawget(_G, APP_KEY) == APP then
    _G[APP_KEY] = nil
  end
end

APP.shutdown = APP.stop

部署后目录应类似：

/sd/apps/hello/app.info
/sd/apps/hello/main.lua
/sd/apps/hello/main.png

然后在 launcher 中重扫 app。当前 launcher 里短按 DOWN 会调用 app.rescan()；也可以重启设备或用自己的脚本调用 app.rescan()。

设备连接 WiFi 后，可以用以下方式确认 IP：

• 打开 Settings app，查看 WiFi/IP 信息。
• 在 Lua 里打印：

local ip, netmask, gateway = wifi.sta.getip()
print("device ip:", ip, netmask, gateway)

• 注册联网事件：

wifi.sta.on("got_ip", function(_, info)
  print("ip:", info.ip)
end)

电脑和设备需要在同一个局域网。假设设备 IP 是 192.168.0.140，浏览器访问：

http://192.168.0.140/devtools/

devtools/package 是自启动 service，入口固定为 /devtools/。兼容入口 /codeeditor/ 会跳转到 /devtools/。

页面主要功能：

DevRun 适合快速试代码；确认后再整理成独立 app 目录和 app.info。

基础前缀：/devtools/api

示例：

curl "http://192.168.0.140/devtools/api/list?path=/sd/apps"

curl -X POST \
  --data-binary @hello/package/main.lua \
  "http://192.168.0.140/devtools/api/code/run"

DevTools 上传直接使用固件原生 PUT /api/system/fs/upload?path=...，读取 API 仍按块返回，浏览器下载走文件流；这些路径都不会把完整文件一次性读入 Lua 内存。 旧 /devtools/api/upload 仍可用于已有客户端，但经过 Lua 请求体通道，速度低于固件原生接口。 单文件最大 64MB。 首次从不含 /reload 的旧版升级时仍需重启设备一次；此后可使用页面顶部的“应用更新”。

上传完整 app 时，推荐先在 DevTools 网页里创建 /sd/apps/hello，再上传 app.info、main.lua、main.png 等文件，最后重扫 app 列表。

• 退出或重载前释放资源：timer:unregister()、key.off()、app.on(name, nil)。
• 回调里不要长时间阻塞；周期任务用 tmr，长循环里检查 app.exiting()。
• UI 资源路径部署后使用 /sd/apps/<app-id>/...。
• 字体用 lv_font_load() 加载后，退出时用 lv_font_free() 释放。
• 网络请求、文件读写建议按 value | nil, err 风格处理失败。
• info.html 是 launcher 嵌入说明页，生成要求见 info页面要求.md。