artdam-cli

ArtDAM 数字资产管理平台命令行工具，支持所有主流 AI Agent工具接入

安装

uv tool install artdam-cli

更新

uv tool install artdam-cli@latest

快速开始

# 登录（首次使用，浏览器 SSO 授权）
artdam login

# 个人 API Key 登录（隐藏输入，适合本机长期使用）
artdam login --api-key

# 搜索资产
artdam search "关键词" --project 1

# 查看资产详情
artdam get 123

# 下载资产
artdam download 123 --out ./downloads

命令说明

素材名的显示口径

开了「只显示 public_id」的项目，search 的「素材名」列、get 的「素材名」行、delete 的 确认文案都显示 public_id（规则同网页端）。

download 落盘名、get 的「路径」行、--json 原始响应照旧给真实文件名——脱敏只在对外面 （发布空间 / 分享链接 / ZIP）由后端做，内部下载不变，见 PR #1036。写脚本时按 display_asset_public_id_only 字段自己判断，别拿显示名当文件名用。

查询命令（viewer 及以上）

artdam login

登录 ArtDAM。默认使用浏览器 SSO，也可使用个人 API Key 或账号密码。

artdam login                         # 浏览器 SSO
artdam login --api-key               # 隐藏输入个人 ab_ API Key
artdam login --password              # 账号密码（仅 admin / 服务账号）

--api-key 会通过只读的 GET /api/auth/me 验证密钥，再保存到 ~/.artdam/config.json（Linux/macOS 为 0600，Windows 收紧为仅当前用户 ACL）。 命令行参数和输出都不会显示密钥。

无人值守脚本和 Agent 可直接使用环境变量，无需执行登录，也不会把密钥写入配置文件：

export ARTDAM_API_KEY='ab_...'
export ARTDAM_BASE_URL='https://artdam.xindong.com' # 可选
artdam search "头盔" --project 1 --json

个人 API Key 代表创建它的用户，最终能力始终是用户在项目中的角色权限 ∩ Key 的权限范围 （scope）。例如 viewer 用户即使 Key 含 write 也不能上传；只有 read 的 Key 不能执行写操作。

artdam search

搜索资产，返回匹配列表。默认只取首页（--limit 条）；加 --all 自动翻页取全部结果 （Agent 场景推荐，避免结果被截断）。--all 最多返回 1000 条，超出会提示用更精确的关键词或 --ext / --folder 收窄，避免在几万条资产上卡死。

artdam search "头盔" --project 1
artdam search "头盔" --project 1 --limit 50
artdam search "头盔" --project 1 --all          # 自动翻页，取全部匹配
artdam search "头盔" --project 1 --all --json   # 全量 JSON 输出（AI Agent 用）
artdam search "头盔" --project 1 --ext jpg       # 按扩展名过滤
artdam search "头盔" --project 1 --ext jpg,png   # 多个扩展名
artdam search "头盔" --project 1 --folder 10

artdam get

查看单个资产详情（含预览链接）。

artdam get 123
artdam get 123 --json   # 输出原始 JSON（AI Agent 用）

artdam download

下载资产文件到本地。

artdam download 123
artdam download 123 --out ./downloads

artdam tags

列出项目标签。

artdam tags --project 1
artdam tags --project 1 --search "角色"
artdam tags --project 1 --json

artdam folders

查看文件夹结构。

artdam folders --project 1
artdam folders --project 1 --json

资产管理（member 及以上）

artdam upload

上传文件到指定项目和文件夹。采用分块上传，支持大文件（最大 10GB），带进度条； 上传前按内容计算 SHA-256，库中已有相同文件则秒传（直接复用，不重复传输）。 单个分块遇到网络抖动（超时 / 5xx）会自动重试，中断时清理服务端会话。

artdam upload ./image.jpg --project 1
artdam upload ./image.jpg --project 1 --folder 10
artdam upload ./big_scene.zip --project 1   # 大文件分块 + 进度条

artdam update

更新资产信息（可同时传多个选项）。

artdam update 123 --name "新文件名"
artdam update 123 --description "新描述"
artdam update 123 --folder 10

artdam delete

软删除资产（可通过 restore 恢复）。

artdam delete 123

artdam restore

恢复已删除的资产。

artdam restore 123

标签管理（member 及以上）

# 给资产添加标签
artdam tag add 123 5

# 从资产移除标签
artdam tag remove 123 5

# 创建新标签
artdam tag create "标签名" --project 1

文件夹管理（member 及以上）

# 创建文件夹
artdam folder create "文件夹名" --project 1
artdam folder create "子文件夹" --project 1 --parent 10

# 删除文件夹
artdam folder delete 10

互动操作（member 及以上）

# 评论
artdam comment 123 "评论内容"

# 评分（1-5 星）
artdam rate 123 4

# 收藏 / 取消收藏
artdam favorite 123
artdam favorite 123 --remove

AI Agent 使用指南

所有查询命令支持 --json 输出原始 JSON，适合 Agent 解析：

artdam search "安妮" --project 1 --json
artdam get 123 --json
artdam tags --project 1 --json
artdam folders --project 1 --json

典型 Agent 工作流

# 1. 登录（本机可用 SSO；无人值守 Agent 推荐 ARTDAM_API_KEY）
export ARTDAM_API_KEY='ab_...'

# 2. 搜索 → 确认 → 下载
artdam search "头盔" --project 1 --json
artdam get 50707 --json
artdam download 50707 --out ./assets

# 3. 搜索 → 批量打标签
artdam search "安妮" --project 1 --json
artdam tag add 50707 5
artdam tag add 50708 5

# 4. 上传并更新描述
artdam upload ./new_asset.jpg --project 1 --folder 10
artdam update <asset_id> --description "AI 生成的场景描述"

注意事项

• --project 参数为数字 ID，不是项目名称
• --json 返回原始 JSON，适合程序解析
• SSO/JWT 或手动输入的 API Key 保存在 ~/.artdam/config.json，仅当前用户可读写
• ARTDAM_API_KEY 优先于配置文件中的登录凭据，且不会被写入配置或输出
• API Key 能力受用户项目角色和 Key scope 双重限制
• artdam delete 是软删除，可用 artdam restore 恢复

配置文件

登录信息保存在 ~/.artdam/config.json：

{
  "base_url": "https://artdam.xindong.com",
  "api_key": "ab_..."
}

SSO 或密码登录时凭据字段为 "token": "eyJ..."。请勿提交此配置文件或在日志中打印其内容。