@freelog-cli/cli

v0.0.13

Published

11 days ago

Freelog CLI - 作品开发与发布工具 (TypeScript)

0High
0Medium
0Low

snnaenu

freelog cli scaffold typescript

Freelog CLI 使用文档

Freelog CLI 是一个用于管理和发布 Freelog 资源的命令行工具。

快速开始

快速开始将引导您完成最基本的资源创建和发布流程。详细的工作流程请参考完整工作流程部分。

1. 登录

freelog-cli login

首次使用需要登录，认证信息会保存在本地。

2. 初始化项目

freelog-cli init my-project

选择项目类型（主题、插件、前端库或其余资源），会自动创建配置文件。

3. 创建资源

freelog-cli create

根据配置文件创建资源，创建成功后会更新配置文件中的 resourceId。

4. 配置版本信息

freelog-cli updateVersion --version 1.0.0 --description "初始版本" --filePath "./dist"

配置版本号、描述和文件路径等信息。

5. 发布版本

freelog-cli publish

发布资源版本到 Freelog 平台。如果资源不存在，会自动创建资源。

6. 添加策略

freelog-cli policy add

为资源添加授权策略并启用。上架资源前必须至少有一个启用的策略。

7. 上架资源

freelog-cli online

将资源状态设置为上架，其他用户才能看到和使用。

提示：

更详细的步骤说明和可选操作（如添加依赖等）请参考完整工作流程
如果资源信息需要更新，可以使用 freelog-cli update 命令
如果资源需要依赖其他资源，可以使用 freelog-cli dep add 命令
注意：策略可以在配置版本信息之前添加，也可以在发布版本之后添加，但必须在上架之前添加并启用至少一个策略

完整工作流程

以下是创建资源并发布版本的完整流程，帮助您快速了解各个命令的使用顺序和关系。

流程概览

1. 登录 (login)
   ↓
2. 初始化项目 (init)
   ↓
3. 创建资源 (create) 或 更新资源信息 (update)
   ↓
4. 配置资源信息 (update) - 可选，设置介绍、封面图、标签等
   ↓
5. 添加策略 (policy add) - 可选，建议在发布前添加
   ↓
6. 配置版本信息 (updateVersion)
   ↓
7. 添加依赖 (dep add) - 可选，如果资源需要依赖其他资源
   ↓
8. 发布版本 (publish)
   ↓
9. 上架资源 (online) - 可选，发布后可以立即上架

详细步骤

步骤 1: 登录

freelog-cli login

首次使用需要登录，认证信息会保存在本地，后续命令无需重复登录。

步骤 2: 初始化项目

freelog-cli init my-project

选择项目类型（主题、插件、前端库或其余资源），会自动创建配置文件：

freelog.resource.config.js - 资源配置文件
freelog.version.config.js - 版本配置文件

步骤 3: 创建资源

方式一：使用 create 命令创建

freelog-cli create

会根据配置文件创建资源，创建成功后会更新配置文件中的 resourceId。

方式二：使用 update 命令创建（如果资源不存在）

freelog-cli update --create

如果配置文件中没有 resourceId，可以使用 --create 选项创建资源。

步骤 4: 配置资源信息（可选）

更新资源的基本信息，如介绍、封面图、标签等：

# 交互式更新
freelog-cli update

# 或使用命令行参数
freelog-cli update --intro "资源介绍" --tags "标签1,标签2" --cover "./cover.jpg"

说明：

create 和 update 的顺序可以调换
可以先创建资源，再更新信息
也可以先更新配置文件（使用 --local-only），再创建资源

步骤 5: 添加策略（可选，建议在发布前添加）

为资源添加授权策略：

freelog-cli policy add

说明：

策略可以在配置版本信息之前或之后添加
建议在发布前添加策略，发布后会自动检查是否有启用的策略
可以添加多个策略，并设置启用/停用状态

步骤 6: 配置版本信息

更新版本号、描述、文件路径等信息：

# 交互式更新
freelog-cli updateVersion

# 或使用命令行参数
freelog-cli updateVersion --version 1.0.0 --description "初始版本" --filePath "./dist"

配置文件字段：

version - 版本号（语义化版本，如：1.0.0）
filePath - 文件路径或目录路径
filename - 文件名（对于非压缩类型的资源）
description - 版本描述

步骤 7: 添加依赖（可选）

如果资源需要依赖其他资源：

# 添加依赖（使用最新版本）
freelog-cli dep add <resourceId>

# 添加依赖并指定版本范围
freelog-cli dep add <resourceId>@^1.0.0

# 添加依赖（默认会交互式选择版本范围格式）
freelog-cli dep add <resourceId>

说明：

添加依赖可能需要签约和支付
如果支付失败，可以选择跳过支付
依赖信息会保存在 freelog.version.config.js 中

步骤 8: 发布版本

发布资源版本到 Freelog 平台：

freelog-cli publish

发布流程：

检查资源配置和版本配置
如果资源不存在，会自动创建资源
压缩文件（对于主题、插件、前端库类型）
上传文件并计算 SHA1
创建版本记录
更新本地配置文件

发布后检查：

如果资源没有启用的策略，会提示添加策略并启用后可以上架资源
如果有启用的策略但资源未上架，会询问是否现在上架

步骤 9: 上架资源（可选）

将资源状态设置为上架：

freelog-cli online

说明：

资源上架后，其他用户才能看到和使用
可以在发布后立即上架，也可以稍后上架
使用 freelog-cli offline 可以下架资源

流程示例

示例 1: 完整流程（包含所有步骤）

# 1. 登录
freelog-cli login

# 2. 初始化项目
freelog-cli init my-theme

# 3. 创建资源
freelog-cli create

# 4. 更新资源信息
freelog-cli update --intro "我的主题" --tags "主题,UI" --cover "./cover.jpg"

# 5. 添加策略
freelog-cli policy add

# 6. 配置版本信息
freelog-cli updateVersion --version 1.0.0 --description "初始版本" --filePath "./dist"

# 7. 添加依赖（如果需要）
freelog-cli dep add 507f1f77bcf86cd799439011

# 8. 发布版本
freelog-cli publish

# 9. 上架资源
freelog-cli online

示例 2: 简化流程（最小步骤）

# 1. 登录
freelog-cli login

# 2. 初始化项目
freelog-cli init my-resource

# 3. 创建资源（会自动创建）
freelog-cli publish  # publish 会自动创建资源（如果不存在）

# 4. 上架资源
freelog-cli online

示例 3: 先配置后创建

# 1. 登录
freelog-cli login

# 2. 初始化项目
freelog-cli init my-resource

# 3. 编辑配置文件，设置资源信息
# 编辑 freelog.resource.config.js

# 4. 只更新配置文件（不创建资源）
freelog-cli update --intro "资源介绍" --local-only

# 5. 创建资源（使用配置文件中的信息）
freelog-cli create

# 6. 配置版本信息
freelog-cli updateVersion --version 1.0.0

# 7. 发布版本
freelog-cli publish

命令顺序说明

必须按顺序执行的命令：

init → create 或 update --create（必须先初始化）
updateVersion → publish（必须先配置版本信息）

可以调换顺序的命令：

create 和 update：可以先创建再更新，也可以先更新配置文件再创建
policy add：可以在 updateVersion 之前或之后添加
dep add：可以在 updateVersion 之前或之后添加

可选步骤：

update：如果资源信息已经配置好，可以跳过
policy add：如果不需要策略，可以跳过
dep add：如果资源没有依赖，可以跳过
online：如果不想立即上架，可以稍后上架

安装

npm install -g freelog-cli-ts

或使用本地安装：

npm install freelog-cli-ts
npx freelog-cli

认证命令

login - 用户登录

登录到 Freelog 平台。

语法：

freelog-cli login [选项]

选项：

-g, --global - 全局登录（认证信息保存在用户主目录）
-u, --username <username> - 用户名或邮箱（可选）
-p, --password <password> - 密码（可选）

示例：

# 交互式登录（工作空间登录）
freelog-cli login

# 全局登录
freelog-cli login --global

# 使用命令行参数登录
freelog-cli login -u myusername -p mypassword

说明：

工作空间登录：认证信息保存在当前项目目录或其父目录的 .freelog-auth 文件中
全局登录：认证信息保存在用户主目录的 .freelog-auth 文件中
工作空间登录优先于全局登录
登录成功后，CLI 会自动保存认证信息，后续命令无需重复登录

logout - 退出登录

清除本地保存的认证信息。

语法：

freelog-cli logout [选项]

选项：

-g, --global - 退出全局登录

示例：

# 退出工作空间登录
freelog-cli logout

# 退出全局登录
freelog-cli logout --global

status - 查看登录状态

查看当前登录状态和用户信息。

语法：

freelog-cli status

示例：

freelog-cli status

说明：

显示当前登录用户信息
显示使用的环境（测试/生产）
显示认证信息存储位置（工作空间/全局）

项目命令

init - 初始化项目

初始化一个新的 Freelog 项目，支持主题、插件、前端库和其余资源类型。

语法：

freelog-cli init [项目名称] [选项]

选项：

-f, --force - 强制清空已存在的目录
--debug - 调试模式

项目类型：

主题 - 创建主题项目模板
插件 - 创建插件项目模板
前端库 - 创建前端库项目模板
其余资源 - 创建其余资源类型项目（仅创建配置文件）

示例：

# 交互式初始化（会提示选择项目类型和名称）
freelog-cli init

# 指定项目名称初始化
freelog-cli init my-theme

# 强制覆盖已存在的目录
freelog-cli init my-theme --force

说明：

对于主题、插件、前端库：会创建项目目录并下载模板，包含完整的项目结构
对于其余资源：在当前目录创建配置文件，需要先登录以选择资源类型
项目名称只能包含英文字母、数字、下划线和横杠

生成的文件：

freelog.resource.config.js - 资源配置文件
freelog.version.config.js - 版本配置文件
README.md - 项目说明文档

create - 创建资源

在 Freelog 平台创建资源，需要先配置好 freelog.resource.config.js 文件。

语法：

freelog-cli create [资源名称] [选项]

选项：

-c, --config <path> - 指定资源配置文件路径
--debug - 调试模式

示例：

# 使用配置文件中的信息创建资源
freelog-cli create

# 指定资源名称创建
freelog-cli create my-resource-name

# 使用指定的配置文件
freelog-cli create -c ./custom-config.js

说明：

命令执行前会显示当前登录用户信息并要求确认
如果配置文件中已有 resourceId，会提示是否继续创建新资源
如果缺少必填字段（resourceName、resourceTypeCode 或 resourceType），会交互式提示输入
创建成功后会更新本地配置文件，保存服务器返回的资源信息（包括 resourceId）

必填字段：

resourceName - 资源名称
resourceTypeCode - 资源类型代码（如：RT001）
resourceType - 资源类型数组（如：['主题']）

update - 更新资源信息

更新资源的基本信息，包括介绍、封面图、标签和状态。

语法：

freelog-cli update [资源ID或名称] [选项]

选项：

-c, --config <path> - 指定资源配置文件路径
--intro <text> - 资源介绍（最多200个字符）
--cover <path> - 封面图：已上传的图片URL或本地文件路径（本地文件会自动上传）
--tags <tags> - 标签（多个用逗号分隔，单个标签最多20个字符）
--status <status> - 资源状态（1:上架 4:下架）
--local-only - 只更新配置文件，不同步到服务器
--create - 如果资源不存在则创建资源
--debug - 调试模式

示例：

# 交互式更新（会提示选择要更新的字段）
freelog-cli update

# 更新资源介绍
freelog-cli update --intro "这是更新后的介绍"

# 更新封面图（本地文件会自动上传）
freelog-cli update --cover "./images/cover.jpg"

# 更新封面图（使用已上传的URL）
freelog-cli update --cover "https://image.freelog.com/preview-image/xxx.jpg"

# 更新标签
freelog-cli update --tags "React,Vue,UI"

# 更新资源状态（上架）
freelog-cli update --status 1

# 同时更新多个字段
freelog-cli update --intro "新介绍" --tags "新标签" --status 1

# 指定资源ID更新
freelog-cli update 507f1f77bcf86cd799439011 --intro "新介绍"

# 只更新配置文件，不同步到服务器
freelog-cli update --intro "新介绍" --local-only

# 如果资源不存在则创建资源
freelog-cli update --intro "新介绍" --create

说明：

命令执行前会显示当前登录用户信息并要求确认（使用 --local-only 且不需要上传封面图时不需要登录）
如果不指定资源ID或名称，会从 freelog.resource.config.js 中读取 resourceId
如果不提供任何选项，会交互式选择要更新的字段
默认行为：更新前会先同步服务器上的资源信息，然后更新服务器和本地配置文件
--local-only 选项：只更新本地配置文件，不调用 API 同步到服务器
- 使用此选项时，封面图必须是已上传的URL（不能是本地文件路径）
- 不需要登录（除非需要上传封面图）
--create 选项：如果资源不存在，会自动创建资源
- 需要确保配置文件中包含必填字段（resourceName、resourceTypeCode、resourceType）
更新成功后会同时更新服务器和本地配置文件（除非使用 --local-only）

可更新的字段：

intro - 资源介绍（支持 Markdown 格式，最多200个字符）
coverImages - 封面图（单张，支持本地文件路径或已上传的URL）
tags - 标签列表（最多20个，单个标签最多20个字符）
status - 资源状态（1:上架 4:下架）

注意事项：

封面图如果是本地文件路径，会自动上传到 Freelog 存储服务
封面图不支持外部URL（非 https://image.freelog.com/preview-image 开头的URL）
标签会自动去重，如果输入了重复标签会提示确认
策略信息会从服务器同步，但不会通过此命令修改

publish - 发布版本

发布资源版本到 Freelog 平台。

语法：

freelog-cli publish [选项]

选项：

-c, --config <path> - 指定配置文件路径
-m, --message <message> - 版本更新说明
--debug - 调试模式

示例：

# 发布版本
freelog-cli publish

# 指定配置文件
freelog-cli publish -c ./custom-config.js

# 指定版本说明
freelog-cli publish -m "修复了若干bug"

说明：

命令执行前会显示当前登录用户信息并要求确认
会自动加载 freelog.resource.config.js 和 freelog.version.config.js 配置文件
如果资源不存在，会自动创建资源
对于主题、插件、前端库类型，会自动压缩 filePath 指定的目录为 ZIP 文件
对于其他类型，直接上传 filePath 指定的文件
会自动计算文件的 SHA1 值，如果服务器已存在相同 SHA1 的文件，则不会重复上传
发布成功后会更新本地配置文件
发布成功后会自动检查：
- 如果资源没有启用的策略，会提示添加策略并启用后可以上架资源
- 如果有启用的策略但资源未上架，会询问是否现在上架

配置文件要求：

freelog.version.config.js 中需要配置：
- version - 版本号（如：1.0.0）
- filePath - 文件路径或目录路径（可选，如：dist）
  - 对于主题、插件、前端库：应为目录路径，会自动压缩为 ZIP
  - 对于其他类型：可以为空或目录路径，会与 filename 组合
- filename - 文件名（必填，对于不需要压缩的资源类型）
- description - 版本描述（可选，如果为空会提示输入）

文件处理：

主题、插件、前端库：
- filePath 应为目录路径（如：dist），会自动压缩为 ZIP
- 压缩后的文件名为：{resourceName}-{version}.zip
其他类型：
- filename 必填（如：index.js）
- filePath 可选：
  - 如果 filePath 为空：文件路径为当前目录 + filename（如：./index.js）
  - 如果 filePath 不为空：文件路径为 filePath + filename（如：dist/index.js）

syncr - 同步资源信息

从服务器同步资源信息到本地配置文件。

语法：

freelog-cli syncr [资源ID或名称] [选项]

选项：

-c, --config <path> - 指定配置文件路径
--debug - 调试模式

示例：

# 从配置文件读取 resourceId 并同步
freelog-cli syncr

# 指定资源ID同步
freelog-cli syncr 507f1f77bcf86cd799439011

# 指定资源名称同步
freelog-cli syncr my-resource-name

# 使用指定的配置文件
freelog-cli syncr -c ./custom-config.js

说明：

命令执行前会显示当前登录用户信息并要求确认
如果不指定资源ID或名称，会从 freelog.resource.config.js 中读取 resourceId
同步成功后会更新本地 freelog.resource.config.js 文件
同步的信息包括：resourceId、resourceName、resourceType、resourceTitle、intro、coverImages、tags、status、policies 等

同步的字段：

resourceId - 资源ID
resourceName - 资源名称
resourceType - 资源类型数组
resourceTitle - 资源标题
resourceTypeCode - 资源类型代码
intro - 资源介绍
coverImages - 封面图列表
tags - 标签列表
status - 资源状态
policies - 策略信息

syncv - 同步版本信息

从服务器同步版本信息到本地配置文件。

语法：

freelog-cli syncv [版本号] [选项]

参数：

[版本号] - 可选，指定要同步的版本号或 latest（不传则使用配置文件版本或最新版本）

选项：

-c, --config <path> - 指定配置文件路径
--debug - 调试模式

示例：

# 从配置文件读取 resourceId 并同步最新版本
freelog-cli syncv

# 同步指定版本
freelog-cli syncv 1.0.0

# 同步最新版本
freelog-cli syncv latest

说明：

命令执行前会显示当前登录用户信息并要求确认
资源ID从 freelog.resource.config.js 中读取，如果不存在会提示先同步资源信息
如果不指定版本号，会提示使用本地配置的版本或最新版本
如果目标版本低于当前配置版本，会显示警告并提示线上最新版本，需要确认是否继续
同步成功后会更新本地 freelog.version.config.js 文件
资源信息优先从 version.config 获取，如果没有则从 resource.config 获取

同步的字段：

version - 版本号
versionId - 版本ID
fileSha1 - 文件SHA1值
description - 版本描述
dependencies - 依赖列表
upcastResources - 上抛资源列表
resourceId - 资源ID
resourceName - 资源名称
resourceType - 资源类型

updateVersion - 更新版本配置信息

更新版本配置文件中的版本号、描述、文件名和文件路径。

语法：

freelog-cli updateVersion [选项]

选项：

-c, --config <path> - 指定版本配置文件路径
--version <version> - 版本号（格式: x.y.z）
--description <text> - 版本描述
--filename <filename> - 文件名
--filePath <path> - 文件路径（相对于当前目录）
--debug - 调试模式

示例：

# 交互式更新（会提示选择要更新的字段）
freelog-cli updateVersion

# 更新版本号
freelog-cli updateVersion --version 1.1.0

# 更新版本描述
freelog-cli updateVersion --description "修复了若干bug"

# 更新文件名
freelog-cli updateVersion --filename "my-resource-v1.1.0.zip"

# 更新文件路径
freelog-cli updateVersion --filePath "./dist/build"

# 同时更新多个字段
freelog-cli updateVersion --version 1.1.0 --description "新版本" --filename "v1.1.0.zip"

说明：

命令执行前会显示当前登录用户信息并要求确认
如果不提供任何参数，会交互式选择要更新的字段
版本号格式验证：必须符合 x.y.z 格式（如：1.0.0）
文件路径验证：会检查文件或目录是否存在
更新成功后会保存到配置文件，保留注释和格式

可更新的字段：

version - 版本号（语义化版本，如：1.0.0）
description - 版本描述
filename - 文件名（用于非压缩类型的资源）
filePath - 文件路径或目录路径（相对于配置文件）

online - 上架资源

将资源状态设置为上架。

语法：

freelog-cli online [资源ID或名称] [选项]

选项：

-c, --config <path> - 指定配置文件路径
--debug - 调试模式

示例：

# 从配置文件读取 resourceId 并上架
freelog-cli online

# 指定资源ID上架
freelog-cli online 507f1f77bcf86cd799439011

# 指定资源名称上架
freelog-cli online my-resource-name

# 使用指定的配置文件
freelog-cli online -c ./custom-config.js

说明：

命令执行前会显示当前登录用户信息并要求确认
如果不指定资源ID或名称，会从 freelog.resource.config.js 中读取 resourceId
上架操作会将资源状态设置为 1（上架）
上架成功后会自动更新本地配置文件

offline - 下架资源

将资源状态设置为下架。

语法：

freelog-cli offline [资源ID或名称] [选项]

选项：

-c, --config <path> - 指定配置文件路径
--debug - 调试模式

示例：

# 从配置文件读取 resourceId 并下架
freelog-cli offline

# 指定资源ID下架
freelog-cli offline 507f1f77bcf86cd799439011

# 指定资源名称下架
freelog-cli offline my-resource-name

# 使用指定的配置文件
freelog-cli offline -c ./custom-config.js

说明：

命令执行前会显示当前登录用户信息并要求确认
如果不指定资源ID或名称，会从 freelog.resource.config.js 中读取 resourceId
下架操作会将资源状态设置为 4（下架）
下架成功后会自动更新本地配置文件

依赖管理命令

dep add - 添加依赖

为资源添加依赖，支持完整的签约支付流程。

语法：

freelog-cli dep add <resourceIdOrName> [选项]

选项：

-c, --config <path> - 指定配置文件路径
--debug - 调试模式

示例：

# 添加依赖（会提示选择版本范围格式）
freelog-cli dep add 507f1f77bcf86cd799439011

# 添加依赖并指定版本范围
freelog-cli dep add 507f1f77bcf86cd799439011@^1.0.0

# 使用资源名称添加
freelog-cli dep add my-resource-name

说明：

命令执行前会显示当前登录用户信息并要求确认
支持通过资源ID或资源名称添加依赖
添加依赖前会自动检查循环依赖，如果检测到循环依赖会提示并终止操作（在用户选择版本之前）
如果命令行指定了版本（如 dep add resourceId@^1.0.0），直接使用指定版本
如果没有指定版本，会获取最新版本并让用户选择版本范围格式：
- Minor最新方式 (^最新版本) - 兼容版本，允许次版本和补丁版本更新（默认推荐）
- Patch最新方式 (~最新版本) - 近似版本，仅允许补丁版本更新
- 精确版本 (最新版本号) - 固定版本，不允许任何更新
- 任意版本 (*) - 总是使用最新版本
如果依赖资源需要签约，会自动处理签约流程
如果依赖资源需要支付，会自动处理支付流程（可选择跳过支付）
添加成功后会更新 freelog.version.config.js 中的 dependencies 字段

版本范围格式（根据 semver 规范）：

^1.0.0 - 兼容版本（1.0.0 <= version < 2.0.0），允许次版本和补丁版本更新
~1.0.0 - 近似版本（1.0.0 <= version < 1.1.0），仅允许补丁版本更新
1.0.0 - 精确版本，不允许任何更新
* - 任意版本，总是使用最新版本

dep remove - 移除依赖

从资源配置中移除依赖。

语法：

freelog-cli dep remove <resourceIdOrName> [选项]

选项：

-c, --config <path> - 指定配置文件路径
--debug - 调试模式

示例：

# 移除依赖
freelog-cli dep remove 507f1f77bcf86cd799439011

# 使用资源名称移除
freelog-cli dep remove my-resource-name

说明：

从本地配置文件中移除依赖，不会影响服务器上的资源
移除成功后会更新 freelog.version.config.js 文件

dep list - 查看依赖列表

查看当前资源的所有依赖。

语法：

freelog-cli dep list [选项]

选项：

--tree - 以树形结构显示（包含依赖的依赖）
-c, --config <path> - 指定配置文件路径
--debug - 调试模式

示例：

# 查看依赖列表
freelog-cli dep list

# 以树形结构显示
freelog-cli dep list --tree

说明：

显示所有依赖的资源ID、名称和版本范围
使用 --tree 选项可以显示依赖的依赖（递归显示）

dep update - 修改依赖版本范围

修改依赖的版本范围配置。

语法：

freelog-cli dep update <resourceIdOrName> [选项]

选项：

-v, --version <version> - 指定版本范围（如 ^1.0.0、~2.3.0、*、1.2.3）
-c, --config <path> - 指定配置文件路径
--debug - 调试模式

示例：

# 交互式修改依赖版本范围
freelog-cli dep update 507f1f77bcf86cd799439011

# 直接指定版本范围
freelog-cli dep update 507f1f77bcf86cd799439011 -v ^1.0.0

# 使用资源名称
freelog-cli dep update my-resource-name -v ~2.3.0

说明：

修改指定依赖的版本范围配置
如果使用 -v, --version 选项，直接使用指定的版本范围
如果不指定版本范围，会交互式选择版本范围格式（类似 dep add 的版本选择）
更新成功后会更新 freelog.version.config.js 文件

策略管理命令

policy add - 添加授权策略

为资源添加授权策略。

语法：

freelog-cli policy add [选项]

选项：

-c, --config <path> - 指定资源配置文件路径
--debug - 调试模式

示例：

# 交互式添加策略
freelog-cli policy add

说明：

命令执行前会显示当前登录用户信息并要求确认
交互式选择策略模板
输入策略名称
填写策略参数（会显示完整的策略预览，参数位置用黄色标记）
预览策略翻译
选择策略的启用状态（启用/停用）
添加成功后会更新 freelog.resource.config.js 中的 policies 字段
如果服务器更新失败，会自动回滚配置文件

策略参数说明：

策略参数预览会显示完整的策略内容，参数位置用 【参数X: 参数名称(类型)】 标记
如果参数名称和类型相同，只显示一个（如：【参数1: 时间单位】）
已填写的参数会显示实际值（绿色）
未填写的参数显示标记（黄色）

policy list - 列出策略

列出资源的所有策略并管理策略状态（启用/停用）。

语法：

freelog-cli policy list [选项]

选项：

-c, --config <path> - 指定资源配置文件路径
--debug - 调试模式

示例：

# 列出所有策略
freelog-cli policy list

说明：

显示所有策略的名称、状态和策略文本
可以交互式启用或停用策略
更新成功后会同步到服务器和本地配置文件

配置文件说明

freelog.resource.config.js

资源配置文件，包含资源的基本信息。

主要字段：

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | resourceId | string | 否 | 资源ID（24位十六进制字符串，创建资源后自动填充） | | resourceName | string | 是 | 资源名称（用于标识资源） | | resourceType | string[] | 是 | 资源类型数组（如：['主题']、['插件']） | | resourceTypeCode | string | 是 | 资源类型代码（如：RT001） | | resourceTitle | string | 否 | 资源标题（显示给用户的标题） | | intro | string | 否 | 资源介绍（支持 Markdown 格式，最多200个字符） | | coverImages | string[] | 否 | 封面图URL列表（单张，支持本地文件路径） | | tags | string[] | 否 | 标签列表（最多20个，单个标签最多20个字符） | | status | number | 否 | 资源状态（0:待发行 1:上架 2:冻结 4:下架） | | policies | PolicyInfo[] | 否 | 策略信息列表 |

配置文件示例：

const config = {
  resourceId: "",
  resourceName: "my-theme",
  resourceType: ["主题"],
  resourceTypeCode: "RT001",
  resourceTitle: "我的主题",
  intro: "这是一个漂亮的主题",
  coverImages: ["https://image.freelog.com/preview-image/xxx.jpg"],
  tags: ["主题", "UI"],
  status: 0,
  policies: [
    {
      policyName: "免费策略",
      policyText: "免费使用",
      status: 1,
      policyId: "" // 添加后自动填充
    }
  ]
};

module.exports = config;

freelog.version.config.js

版本配置文件，包含版本相关的信息。

主要字段：

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | version | string | 是 | 版本号（语义化版本，如：1.0.0） | | filePath | string | 是 | 文件路径或目录路径（如：dist） | | filename | string | 否 | 文件名（用于非压缩类型的资源） | | fileSha1 | string | 否 | 文件SHA1值（40位十六进制，发布后自动填充） | | versionId | string | 否 | 版本ID（发布后自动填充） | | description | string | 否 | 版本描述（支持 Markdown 格式） | | dependencies | Dependency[] | 否 | 依赖列表 | | baseUpcastResources | BaseUpcastResource[] | 否 | 上抛资源列表 | | resourceId | string | 否 | 资源ID（会从 resource.config 获取） | | resourceName | string | 否 | 资源名称（会从 resource.config 获取） | | resourceType | string | 否 | 资源类型（会从 resource.config 获取） | | userId | number | 否 | 用户ID（创建资源后自动填充） |

依赖格式：

dependencies: [
  {
    resourceId: "507f1f77bcf86cd799439011",
    resourceName: "依赖资源名称", // 可选，用于可读性
    versionRange: "^1.0.0" // 版本范围：^1.0.0, ~2.3.0, *, 1.2.3
  }
]

配置文件示例：

const config = {
  resourceId: "",
  resourceType: "主题",
  resourceName: "my-theme",
  userId: 0,
  description: "初始版本",
  version: "1.0.0",
  versionId: "",
  fileSha1: "",
  dependencies: [],
  upcastResources: [],
  resolveResources: [],
  systemProperty: {},
  customProperty: {},
  customPropertyDescriptors: [],
  catalogueProperty: {},
  createDate: "",
  filename: "",
  baseUpcastResources: [],
  batchSignContracts: [],
  inputAttrs: [],
  authExcludedItems: [],
  filePath: "dist"
};

module.exports = config;

文件路径说明：

主题、插件、前端库：filePath 应为目录路径，会自动压缩为 ZIP
其他类型：filePath 可以是目录或文件路径，filename 用于指定文件名

常见问题

1. 如何查看当前登录状态？

freelog-cli status

2. 如何切换测试环境和生产环境？

在命令前添加 -t 选项使用测试环境：

freelog-cli -t login

默认使用生产环境。

3. 创建资源失败怎么办？

使用 --debug 选项查看详细的请求信息：

freelog-cli create --debug

这会显示：

调用的接口
完整的请求URL
请求方法
请求数据（JSON格式）

4. 工作空间登录和全局登录的区别？

工作空间登录：认证信息保存在项目目录或其父目录的 .freelog-auth 文件中，只对当前项目有效
全局登录：认证信息保存在用户主目录的 .freelog-auth 文件中，对所有项目有效

工作空间登录优先于全局登录。

5. 如何查看命令帮助？

# 查看所有命令
freelog-cli --help

# 查看特定命令的帮助
freelog-cli create --help
freelog-cli publish --help
freelog-cli dep --help

6. 如何更新版本配置信息？

使用 updateVersion 命令：

# 交互式更新
freelog-cli updateVersion

# 命令行更新
freelog-cli updateVersion --version 1.1.0 --description "新版本"

7. 如何管理依赖？

# 添加依赖
freelog-cli dep add <resourceId>

# 查看依赖列表
freelog-cli dep list

# 修改依赖版本范围
freelog-cli dep update <resourceId>

# 直接指定版本范围
freelog-cli dep update <resourceId> -v ^1.0.0

8. 如何上架/下架资源？

# 上架资源
freelog-cli online

# 下架资源
freelog-cli offline

9. 版本号格式要求？

版本号必须遵循语义化版本规范：x.y.z

x - 主版本号（不兼容的 API 修改）
y - 次版本号（向下兼容的功能性新增）
z - 修订号（向下兼容的问题修正）

示例：1.0.0、2.1.3、0.1.0

10. 依赖版本范围格式？

支持以下版本范围格式：

^1.0.0 - 兼容版本（1.0.0 <= version < 2.0.0）
~2.3.0 - 近似版本（2.3.0 <= version < 2.4.0）
* - 任意版本
1.2.3 - 精确版本

11. 封面图支持哪些格式？

已上传的图片URL：必须以 https://image.freelog.com/preview-image 开头
本地文件路径：会自动上传到 Freelog 存储服务，上传后返回的URL会保存到配置文件
不支持：外部URL（非 Freelog 存储服务的URL）

12. 策略添加失败会回滚吗？

是的。如果策略添加到配置文件后，服务器更新失败，会自动回滚配置文件到添加前的状态，并提示用户。

最佳实践

1. 项目初始化

# 推荐流程
freelog-cli login
freelog-cli init my-project
# 选择项目类型
# 编辑配置文件
freelog-cli create

2. 版本管理

使用语义化版本号：1.0.0、1.1.0、2.0.0
每次发布前更新版本号
使用 updateVersion 命令更新版本配置

3. 依赖管理

使用版本范围而不是精确版本（如：^1.0.0 而不是 1.0.0）
使用 dep update 修改依赖的版本范围配置
使用 dep list --tree 查看依赖树

4. 配置文件管理

将配置文件纳入版本控制（Git）
不要手动修改自动生成的字段（如 resourceId、versionId）
定期使用 syncr 和 syncv 同步服务器信息

5. 发布流程

# 推荐发布流程
freelog-cli updateVersion --version 1.1.0 --description "新功能"
freelog-cli publish
# 如果发布成功且没有启用的策略，会提示添加策略
# 如果有启用的策略但未上架，会询问是否上架
freelog-cli online  # 如果需要上架

6. 错误处理

使用 --debug 选项查看详细错误信息
检查配置文件格式是否正确
确认文件路径是否存在
检查网络连接和登录状态

交互操作说明

在使用 CLI 进行交互式操作时，请注意以下操作方式：

多选操作（Checkbox）

当命令提示您进行多选时（例如选择要更新的字段），请使用以下操作方式：

空格键：选中/取消选中当前项
方向键（↑↓）：上下移动光标
回车键（Enter）：确认选择并继续

示例场景：

选择要更新的字段（update 命令）
选择要同步的资源（syncr 命令）

单选操作（List）

当命令提示您进行单选时（例如选择资源类型、状态等），请使用以下操作方式：

方向键（↑↓）：上下移动光标
回车键（Enter）：确认选择并继续

确认操作（Confirm）

当命令提示您确认操作时，请使用以下操作方式：

Y/y 或 回车键：确认操作
N/n：取消操作

命令流程图

创建和发布资源的完整流程

1. 登录 (login)
   ↓
2. 初始化项目 (init)
   ↓
3. 配置资源信息 (编辑 freelog.resource.config.js)
   ↓
4. 创建资源 (create)
   ↓
5. 添加策略 (policy add) [可选]
   ↓
6. 配置版本信息 (编辑 freelog.version.config.js)
   ↓
7. 添加依赖 (dep add) [可选]
   ↓
8. 发布版本 (publish)
   ↓
9. 上架资源 (online)

更新资源的流程

1. 登录 (login)
   ↓
2. 更新资源信息 (update)
   ↓
3. 更新版本配置 (updateVersion) [可选]
   ↓
4. 发布新版本 (publish)

同步信息的流程

1. 登录 (login)
   ↓
2. 同步资源信息 (syncr)
   ↓
3. 同步版本信息 (syncv)

依赖管理流程

1. 登录 (login)
   ↓
2. 查看依赖列表 (dep list)
   ↓
3. 添加依赖 (dep add)
   ↓
4. 修改依赖版本范围 (dep update) [可选]

注意事项

登录状态：大部分命令需要先登录，执行前会显示当前登录用户信息并要求确认
配置文件：确保配置文件格式正确，字段类型匹配
文件路径：filePath 可以是相对路径或绝对路径，确保文件或目录存在
资源类型：resourceType 必须是数组格式，如：['主题']
版本号：遵循语义化版本规范（如：1.0.0）
文件大小：上传的文件大小有限制，请参考 Freelog 平台文档
依赖管理：添加依赖可能需要签约和支付，请确保账户有足够余额
策略管理：策略文本支持 Markdown 格式，可以包含多行内容
配置文件格式：支持 .js 和 .ts 格式，建议使用 .js 格式（更简单）
封面图：本地文件会自动上传，不支持手动编辑配置文件中的本地路径

快速参考

常用命令组合

首次创建和发布资源：

freelog-cli login
freelog-cli init my-project
# 编辑配置文件
freelog-cli create
freelog-cli publish
freelog-cli online

更新资源并发布新版本：

freelog-cli update --intro "更新后的介绍"
freelog-cli updateVersion --version 1.1.0 --description "新功能"
freelog-cli publish

添加依赖并发布：

freelog-cli dep add <resourceId>
freelog-cli publish

同步最新信息：

freelog-cli syncr
freelog-cli syncv
freelog-cli dep update <resourceId> -v ^1.0.0

命令速查表

| 命令 | 功能 | 常用选项 | |------|------|---------| | login | 登录 | -g (全局登录) | | init | 初始化项目 | -f (强制覆盖) | | create | 创建资源 | -c (指定配置) | | update | 更新资源信息 | --intro, --tags, --status | | updateVersion | 更新版本配置 | --version, --description, --filePath | | publish | 发布版本 | -c (指定配置) | | online | 上架资源 | -c (指定配置) | | offline | 下架资源 | -c (指定配置) | | syncr | 同步资源信息 | -c (指定配置) | | syncv | 同步版本信息 | [version] (版本号位置参数) | | dep add | 添加依赖 | -c (指定配置) | | dep list | 查看依赖 | --tree (树形显示) | | dep update | 修改依赖版本范围 | -v (指定版本范围) | | dep remove | 移除依赖 | -c (指定配置) | | policy add | 添加策略 | -c (指定配置) | | policy list | 列出策略 | -c (指定配置) |

版本历史

查看 CLI 版本：

freelog-cli --version

查看更新日志和功能变更，请参考项目的 CHANGELOG.md 文件。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Freelog CLI 使用文档

目录

快速开始

1. 登录

2. 初始化项目

3. 创建资源

4. 配置版本信息

5. 发布版本

6. 添加策略

7. 上架资源

完整工作流程

流程概览

详细步骤

步骤 1: 登录

步骤 2: 初始化项目

步骤 3: 创建资源

步骤 4: 配置资源信息（可选）

步骤 5: 添加策略（可选，建议在发布前添加）

步骤 6: 配置版本信息

步骤 7: 添加依赖（可选）

步骤 8: 发布版本

步骤 9: 上架资源（可选）

流程示例

命令顺序说明

安装

认证命令

login - 用户登录

logout - 退出登录

status - 查看登录状态

项目命令

init - 初始化项目

create - 创建资源

update - 更新资源信息

publish - 发布版本

syncr - 同步资源信息

syncv - 同步版本信息

updateVersion - 更新版本配置信息

online - 上架资源

offline - 下架资源

依赖管理命令

dep add - 添加依赖

dep remove - 移除依赖

dep list - 查看依赖列表

dep update - 修改依赖版本范围

策略管理命令

policy add - 添加授权策略

policy list - 列出策略

配置文件说明

freelog.resource.config.js

freelog.version.config.js

常见问题

1. 如何查看当前登录状态？

2. 如何切换测试环境和生产环境？

3. 创建资源失败怎么办？

4. 工作空间登录和全局登录的区别？

5. 如何查看命令帮助？

6. 如何更新版本配置信息？

7. 如何管理依赖？

8. 如何上架/下架资源？

9. 版本号格式要求？

10. 依赖版本范围格式？

11. 封面图支持哪些格式？

12. 策略添加失败会回滚吗？

最佳实践

1. 项目初始化

2. 版本管理

3. 依赖管理

4. 配置文件管理

5. 发布流程

6. 错误处理

交互操作说明

多选操作（Checkbox）

单选操作（List）

确认操作（Confirm）