lightning-artifacts

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Lightning AI Artifacts (durable shareable file links)

Lightning AI Artifacts(持久化可分享文件链接)

Publish any file to a teamspace and get back a durable public URL —
https://lightning.ai/artifacts/<id>
— that anyone can open with no Lightning login, renders inline in the browser (HTML/PDF/images), and never expires. The control plane streams the bytes from storage on every request, so unlike a presigned S3 URL there is no ~1h cap. Great for agent-generated one-pagers, reports, dashboards, dataset samples, or build artifacts.
This whole flow runs through the
lightning
CLI
(from the
lightning-sdk
package):
lightning cp
/
ls
/
rm
handle the files, and
lightning api
— a
gh api
-style raw HTTP client — makes the two publish calls around them. No Python, no SDK code, not even a
curl
.
将任意文件发布到 teamspace 后,你将获得一个持久化公开URL——
https://lightning.ai/artifacts/<id>
——任何人无需登录 Lightning 账号即可打开,支持在浏览器内联渲染(HTML/PDF/图片),且永不过期。 控制平面会在每次请求时从存储中流式传输文件字节,因此与预签名 S3 URL 不同,它没有约1小时的有效期限制。非常适合分享 Agent 生成的单页文档、报告、仪表盘、数据集样本或构建产物。
整个流程完全通过
lightning
CLI 完成
(来自
lightning-sdk
包):
lightning cp
/
ls
/
rm
用于处理文件,而
lightning api
——一个 类似
gh api
的原生HTTP客户端——负责执行前后的两次发布调用。无需编写Python代码,无需调用SDK,甚至不用写
curl
命令。

Setup & auth

安装与认证

bash
undefined
bash
undefined

Use the Lightning AI CLI from the current env; install or upgrade it there if it's missing or older than 2026.9.18

Use the Lightning AI CLI from the current env; install or upgrade it there if it's missing or older than 2026.9.18

v=$(lightning --version 2>/dev/null | sed -n 's/^Lightning CLI version //p') [ -n "$v" ] && [ "$(printf '%s\n' 2026.9.18 "$v" | sort -V | head -1)" = 2026.9.18 ]
|| uv pip install -U lightning-sdk || python3 -m pip install -U lightning-sdk lightning --version # must print "Lightning CLI version …"; if not, see the table below lightning login # interactive browser sign-in — enough for everything here
v=$(lightning --version 2>/dev/null | sed -n 's/^Lightning CLI version //p') [ -n "$v" ] && [ "$(printf '%s\n' 2026.9.18 "$v" | sort -V | head -1)" = 2026.9.18 ]
|| uv pip install -U lightning-sdk || python3 -m pip install -U lightning-sdk lightning --version # must print "Lightning CLI version …"; if not, see the table below lightning login # interactive browser sign-in — enough for everything here

or: export LIGHTNING_API_KEY=... # non-interactive alternative (CI, agents)

or: export LIGHTNING_API_KEY=... # non-interactive alternative (CI, agents)


Either credential works for **every call in this skill** — no token minting or
extra auth steps. Get a key from lightning.ai → user/org settings, or
`lightning api-key create --org <org> --name artifacts`. **Never hardcode the
key** — read it from the environment. To target a non-prod control plane, set
`LIGHTNING_CLOUD_URL` (default `https://lightning.ai`).

This uses, and if needed installs into, the environment the agent runs in (the user's project
venv, a conda env, …). Then call plain `lightning …` everywhere. If setup doesn't go cleanly:

| Symptom | Fix |
|---|---|
| Both installs fail: no active env, or pip refuses with `externally-managed-environment` | Install it on its own instead: `uv tool install lightning-sdk` (or `pipx install lightning-sdk`), then call `"$(uv tool dir --bin)/lightning"` if that dir isn't on `PATH` |
| `lightning --version` still prints no `Lightning CLI version` line after installing | `command -v lightning` shows which one runs. Another tool owns the name (PyTorch Lightning also installs a `lightning` command), or the env you installed into isn't on `PATH`: activate it (`source .venv/bin/activate`) or call its `bin/lightning` by full path |
| `No such command`, `No such option` or `unexpected extra argument` | The CLI is older than this skill expects: `uv pip install -U lightning-sdk` (or `pip install -U lightning-sdk`) in the env `command -v lightning` points into; `uv tool upgrade lightning-sdk` for a uv tool install |
| The upgrade fails on a version conflict with the project's own pins | Don't fight the pins: install it outside the project with `uv tool install lightning-sdk` and call `"$(uv tool dir --bin)/lightning"` |
| Installing is blocked (read-only env or home, agent sandbox) | Skip it and run each command as `UV_CACHE_DIR="${TMPDIR:-/tmp}/uv" uvx lightning-sdk …` |
| Every call fails on SSL/certificates, even `lightning --version` (`Could not find a suitable TLS CA certificate bundle`), only inside an agent sandbox | A `**/*.pem` read-deny rule is hiding certifi's public CA bundle (`site-packages/certifi/cacert.pem`). Allow that one path; don't disable the sandbox |

`lightning api` flags: `-X` method, `-f key=val` string field, `-F key=val`
typed field, `-H` header, `--input <file>` request body (`--input -` to pipe
one), `-q` jq filter (needs the `jq` binary for `-q`), `-i` include response
headers, `--silent` no output. Fields with no `-X` make it a POST. Fields are JSON body for POST/PUT-with-body and **query
params** when the request also has `--input` or is a GET.

两种凭证都可用于**本skill中的所有调用**——无需生成token或额外的认证步骤。你可以从 lightning.ai 的用户/组织设置中获取密钥,或者通过命令 `lightning api-key create --org <org> --name artifacts` 创建。**切勿硬编码密钥**——请从环境变量中读取。如果要指向非生产环境的控制平面,请设置 `LIGHTNING_CLOUD_URL`(默认为 `https://lightning.ai`)。

本skill会使用Agent运行环境(用户的项目venv、conda环境等)中的Lightning CLI,若环境中没有则会安装到该环境中。之后所有地方都直接调用 `lightning …` 即可。如果安装过程不顺利,请参考下表:

| 症状 | 解决方法 |
|---|---|
| 两种安装方式都失败:没有激活的环境,或者 pip 以 `externally-managed-environment` 为由拒绝安装 | 改为单独安装:`uv tool install lightning-sdk`(或 `pipx install lightning-sdk`),如果该目录不在 `PATH` 中,则调用 `"$(uv tool dir --bin)/lightning"` |
| 安装后 `lightning --version` 仍然没有输出 `Lightning CLI version` 行 | 用 `command -v lightning` 查看当前运行的是哪个程序。可能是其他工具占用了这个命令名(PyTorch Lightning 也会安装 `lightning` 命令),或者你安装的环境不在 `PATH` 中:激活环境(`source .venv/bin/activate`)或者通过完整路径调用其 `bin/lightning` |
| 出现 `No such command`、`No such option` 或 `unexpected extra argument` 错误 | CLI版本低于本skill的要求:在 `command -v lightning` 指向的环境中执行 `uv pip install -U lightning-sdk`(或 `pip install -U lightning-sdk`);如果是uv tool安装的,则执行 `uv tool upgrade lightning-sdk` |
| 升级因与项目自身的依赖版本冲突而失败 | 不要强行修改依赖:用 `uv tool install lightning-sdk` 安装到项目外部,并调用 `"$(uv tool dir --bin)/lightning"` |
| 安装被阻止(只读环境或home目录、Agent沙箱) | 跳过安装,将每个命令改为 `UV_CACHE_DIR="${TMPDIR:-/tmp}/uv" uvx lightning-sdk …` 的形式运行 |
| 即使是 `lightning --version` 也会因SSL/证书问题失败(`Could not find a suitable TLS CA certificate bundle`),且仅在Agent沙箱中出现 | 是 `**/*.pem` 读取拒绝规则隐藏了certifi的公共CA包(`site-packages/certifi/cacert.pem`)。允许该路径即可;不要禁用沙箱 |

`lightning api` 常用参数:`-X` 指定请求方法,`-f key=val` 传递字符串字段,`-F key=val` 传递类型化字段,`-H` 指定请求头,`--input <file>` 指定请求体(`--input -` 表示从管道读取),`-q` 指定jq过滤规则(`-q` 需要安装 `jq` 二进制文件),`-i` 包含响应头,`--silent` 不输出内容。如果没有指定 `-X` 但有字段参数,则默认是POST请求。对于POST/PUT且有请求体的情况,字段会作为JSON请求体;如果是GET请求或同时指定了 `--input`,则字段会作为**查询参数**。

Resolve the teamspace (do this first)

解析 teamspace(请先执行此步骤)

Artifacts live in a teamspace (a "project" in the REST API). You need three values: the owner name and teamspace name (for
lit://
upload URLs) and the project id (for the REST calls). Never guess. List memberships and, if more than one fits and none is configured, ask the user which to use:
bash
lightning api /v1/memberships -q '.memberships[] | [.name, .projectId, .ownerType, .ownerId] | @tsv'
Capture the row's
projectId
and resolve the owner's name. The membership only carries the owner's id, and the lookup depends on
ownerType
:
bash
PID=<projectId-from-above>
TSNAME=<name-from-above>
OWNER_ID=<ownerId-from-above>
if [ "<ownerType-from-above>" = organization ]; then
  OWNER=$(lightning api "/v1/orgs/$OWNER_ID" | jq -r .name)
else   # a personal teamspace: yours, or another user's you were added to
  OWNER=$(lightning api /v1/users/search -X GET -f "query=$OWNER_ID" \
    | jq -r --arg id "$OWNER_ID" '.users[] | select(.id==$id) | .username')
fi
[ -n "$OWNER" ] && [ "$OWNER" != null ] || echo "could not resolve the owner of $TSNAME — ask the user" >&2
Search by id and match on
.id
exactly (the search is fuzzy); this is the lookup the SDK itself uses. Never fall back to your own username: a wrong owner in the
lit://
path uploads into a different teamspace.
Teamspaces you can access through org-level permissions (rather than direct membership) don't appear in
/v1/memberships
— if the user names one you can't find, ask them for the
<owner>/<teamspace>
pair and the project id. There is no list-projects-by-name endpoint (
/v1/projects?name=…
isn't in the API), so don't try to look it up.
Artifacts 存储在 teamspace 中(即 REST API 中的“project”)。你需要三个值:所有者名称和teamspace名称(用于
lit://
上传URL)以及项目ID(用于REST调用)。切勿猜测。 列出你拥有的成员身份,如果有多个符合条件且没有配置默认值,询问用户要使用哪一个:
bash
lightning api /v1/memberships -q '.memberships[] | [.name, .projectId, .ownerType, .ownerId] | @tsv'
获取对应行的
projectId
,并解析所有者的名称。成员身份信息只包含所有者ID,查找方式取决于
ownerType
:
bash
PID=<projectId-from-above>
TSNAME=<name-from-above>
OWNER_ID=<ownerId-from-above>
if [ "<ownerType-from-above>" = organization ]; then
  OWNER=$(lightning api "/v1/orgs/$OWNER_ID" | jq -r .name)
else   # a personal teamspace: yours, or another user's you were added to
  OWNER=$(lightning api /v1/users/search -X GET -f "query=$OWNER_ID" \
    | jq -r --arg id "$OWNER_ID" '.users[] | select(.id==$id) | .username')
fi
[ -n "$OWNER" ] && [ "$OWNER" != null ] || echo "could not resolve the owner of $TSNAME — ask the user" >&2
通过ID搜索并精确匹配
.id
(搜索是模糊的);这也是SDK自身使用的查找方式。切勿回退到使用你自己的用户名:
lit://
路径中的所有者错误会导致文件上传到错误的 teamspace 中。
通过组织级权限访问的 teamspace(而非直接成员身份)不会出现在
/v1/memberships
中——如果用户指定了一个你找不到的 teamspace,请向用户询问
<owner>/<teamspace>
对和项目ID。目前没有按名称列出项目的接口(API中不存在
/v1/projects?name=…
),所以不要尝试这样查找。

Publish a durable link (the CLI flow)

发布持久化链接(CLI 流程)

A public link (
private=false
, the default below) needs the user's say-so in this request.
"Publish this" or "get me a public link" is authorization — don't ask twice. "Send this to the team" is not: say what the link exposes and get a yes, or use
-F private=true
.
Three calls:
lightning cp
the file into the
artifacts/
drive, read back which storage cluster it landed on, then register the object as a shared artifact. Copy-paste function:
bash
undefined
公开链接(
private=false
,即下文的默认值)需要用户在本次请求中明确同意。
“发布这个”或者“给我一个公开链接”就算是授权——不需要重复询问。“把这个发给团队”则不算:需要说明链接会暴露什么内容并获得用户同意,或者使用
-F private=true
。
总共三次调用:用
lightning cp
将文件上传到
artifacts/
驱动器,读取文件落地的存储集群,然后将该对象注册为共享artifact。可直接复制使用的函数:
bash
undefined

share <local-file> [remote-name] [content-type]

share <local-file> [remote-name] [content-type]

Pretty status goes to stderr; the bare URL is the only thing on stdout, so

Pretty status goes to stderr; the bare URL is the only thing on stdout, so

URL=$(share file.html) captures cleanly while interactive use looks like:

URL=$(share file.html) captures cleanly while interactive use looks like:

✅ Published report.html (text/html; charset=utf-8)

✅ Published report.html (text/html; charset=utf-8)

share() { local FILE="$1" NAME="${2:-$(basename "$1")}" CT="${3:-$(file -b --mime-type "$1")}" local KEY="artifacts/${NAME#artifacts/}" # publish only finds objects under artifacts/

1. upload; the server picks where to store it (see Gotchas)

lightning cp "$FILE" "lit://$OWNER/$TSNAME/$KEY" >&2 || return 1

2. the blob's clusterId from the listing is the storage cluster the

publish call needs (see Gotchas — it is not always the cluster the

upload went through)

local CLUSTER; CLUSTER=$(lightning ls --json "lit://$OWNER/$TSNAME/$KEY" | jq -r '.[0].clusterId')

3. register it -> durable, no-expiry lightning.ai/artifacts/<id>

local LINK; LINK=$(lightning api "/v1/projects/$PID/shared-artifacts" -X POST
-f clusterId="$CLUSTER" -f filename="$KEY" -f contentType="$CT" -F private=false -q .url | tr -d '"') echo "✅ Published $NAME ($CT)" >&2 printf '🔗 ' >&2 echo "$LINK" }
share report.html # -> https://lightning.ai/artifacts/art_... share dashboard.html reports/dash.html text/html # custom remote name + explicit type

When you publish something for the user, always show them the full URL on its
own line (terminals make it clickable) — never just say "done".

The upload path and the publish `filename` must point at the same object — the
`KEY` variable keeps them identical. The server confines shares to the
`artifacts/` folder; if you pass a bare `filename` (no `artifacts/` prefix) to
publish it prepends one, but matching the two explicitly is clearest.

Set `-F private=true` to require an authorized project reader to open the link
(good for internal-only shares); the default `false` is genuinely public.
share() { local FILE="$1" NAME="${2:-$(basename "$1")}" CT="${3:-$(file -b --mime-type "$1")}" local KEY="artifacts/${NAME#artifacts/}" # publish only finds objects under artifacts/

1. upload; the server picks where to store it (see Gotchas)

lightning cp "$FILE" "lit://$OWNER/$TSNAME/$KEY" >&2 || return 1

2. the blob's clusterId from the listing is the storage cluster the

publish call needs (see Gotchas — it is not always the cluster the

upload went through)

local CLUSTER; CLUSTER=$(lightning ls --json "lit://$OWNER/$TSNAME/$KEY" | jq -r '.[0].clusterId')

3. register it -> durable, no-expiry lightning.ai/artifacts/<id>

local LINK; LINK=$(lightning api "/v1/projects/$PID/shared-artifacts" -X POST
-f clusterId="$CLUSTER" -f filename="$KEY" -f contentType="$CT" -F private=false -q .url | tr -d '"') echo "✅ Published $NAME ($CT)" >&2 printf '🔗 ' >&2 echo "$LINK" }
share report.html # -> https://lightning.ai/artifacts/art_... share dashboard.html reports/dash.html text/html # custom remote name + explicit type

当你为用户发布内容时,一定要单独占一行显示完整的URL(终端中会自动变成可点击链接)——不要只说“完成了”。

上传路径和发布时的 `filename` 必须指向同一个对象——`KEY` 变量保证了两者一致。服务器会将共享限制在 `artifacts/` 文件夹内;如果你给发布接口传递的是裸 `filename`(没有 `artifacts/` 前缀),它会自动加上,但显式保持两者一致是最清晰的做法。

设置 `-F private=true` 可以要求链接必须由授权的项目读者才能打开(适合内部共享);默认值 `false` 表示完全公开。

Content types that render inline

可内联渲染的内容类型

file -b --mime-type
guesses most cases; pass an explicit type when the extension is ambiguous. The publish call's
contentType
is what the browser sees on every request (it overrides the stored object's type), so getting it right there is what makes HTML/PDF render instead of download.
FileContent-Type
.html
text/html; charset=utf-8
.pdf
application/pdf
.svg
image/svg+xml
.png
/
.jpg
image/png
/
image/jpeg
.json
/
.txt
/
.csv
application/json
/
text/plain
/
text/csv
anything to force-download
application/octet-stream
file -b --mime-type
可以猜测大多数情况的类型;当文件扩展名有歧义时,请显式指定类型。发布调用中的
contentType
就是浏览器在每次请求时看到的内容类型(它会覆盖存储对象的原有类型),所以正确设置这个值才能让HTML/PDF直接渲染而不是下载。
文件类型Content-Type
.html
text/html; charset=utf-8
.pdf
application/pdf
.svg
image/svg+xml
.png
/
.jpg
image/png
/
image/jpeg
.json
/
.txt
/
.csv
application/json
/
text/plain
/
text/csv
任何需要强制下载的文件
application/octet-stream

List, see what's published, unpublish, delete

列出、查看已发布内容、取消发布、删除

List what's in the drive with
lightning ls
— one level by default,
-r
for every file underneath,
--json
for entries with
size
and the
clusterId
the publish call needs. Listings follow the server's pages automatically, so folders with many thousands of files come back complete:
bash
lightning ls "lit://$OWNER/$TSNAME/artifacts/"              # one level; folders end in /
lightning ls -r "lit://$OWNER/$TSNAME/artifacts/reports"    # full relative file paths
lightning ls --json "lit://$OWNER/$TSNAME/artifacts/reports"
List every published link in the project (
GET /v1/projects/{pid}/shared-artifacts
, newest first — id, filename, content type, public/private, download count, URL):
bash
undefined
用
lightning ls
列出驱动器中的内容
——默认只显示一级,
-r
递归显示所有子文件,
--json
输出包含
size
和发布调用所需的
clusterId
的条目。列表会自动处理服务器的分页,因此包含数千个文件的文件夹也能完整返回:
bash
lightning ls "lit://$OWNER/$TSNAME/artifacts/"              # one level; folders end in /
lightning ls -r "lit://$OWNER/$TSNAME/artifacts/reports"    # full relative file paths
lightning ls --json "lit://$OWNER/$TSNAME/artifacts/reports"
列出项目中所有已发布的链接(
GET /v1/projects/{pid}/shared-artifacts
,按最新排序——包含ID、文件名、内容类型、公开/私有、下载次数、URL):
bash
undefined

shares -> one block per published artifact

shares -> one block per published artifact

shares() { lightning api "/v1/projects/$PID/shared-artifacts" | jq -r '.artifacts // [] | .[] | "(if .private then "🔒" else "🌐" end) (.filename) · ⬇ (.downloads // 0) · (.createdAt // "") id: (.id) 🔗 (.url)"' }

**Unpublish** (revoke the link; the file itself stays in the drive):

```bash
shares() { lightning api "/v1/projects/$PID/shared-artifacts" | jq -r '.artifacts // [] | .[] | "(if .private then "🔒" else "🌐" end) (.filename) · ⬇ (.downloads // 0) · (.createdAt // "") id: (.id) 🔗 (.url)"' }

**取消发布**(撤销链接;文件本身仍保留在驱动器中):

```bash

unshare <artifact-id>

unshare <artifact-id>

unshare() { lightning api "/v1/projects/$PID/shared-artifacts/$1" -X DELETE --silent
&& echo "🗑️ Unpublished $1 — link is dead, file kept in the drive" >&2 }
unshare art_01kxgaep54zzs84arfns1j21wd

**Delete the file itself** (after unpublishing, or to clean up an abandoned
upload) — no cluster id needed; the server removes it wherever it is stored:

```bash
lightning rm "lit://$OWNER/$TSNAME/artifacts/report.html"
lightning rm -r "lit://$OWNER/$TSNAME/artifacts/reports"     # a folder and everything under it
rm
fails on a path that doesn't exist (pass
-f
to ignore) and refuses a folder without
-r
.
Re-publish the same object later (new id, new URL) by repeating the publish call with the same
filename
. Update the contents behind an existing link by re-running
lightning cp
to the same
artifacts/<name>
— published ids keep serving the new bytes. To change the served Content-Type, publish again.
unshare() { lightning api "/v1/projects/$PID/shared-artifacts/$1" -X DELETE --silent
&& echo "🗑️ Unpublished $1 — link is dead, file kept in the drive" >&2 }
unshare art_01kxgaep54zzs84arfns1j21wd

**删除文件本身**(取消发布后,或者清理废弃的上传文件)——不需要集群ID;服务器会从存储它的任何位置删除:

```bash
lightning rm "lit://$OWNER/$TSNAME/artifacts/report.html"
lightning rm -r "lit://$OWNER/$TSNAME/artifacts/reports"     # a folder and everything under it
如果路径不存在,
rm
会失败(传
-f
可忽略错误),并且如果没有
-r
参数,它会拒绝删除文件夹。
之后可以通过重复使用相同
filename
调用发布接口来重新发布同一个对象(会生成新的ID和URL)。如果要更新现有链接背后的内容,只需重新执行
lightning cp
到同一个
artifacts/<name>
路径——已发布的ID会继续提供新的文件内容。如果要修改提供的Content-Type,重新发布一次即可。

Example workflows

示例工作流

Prompts this skill handles: "share this HTML report as a permanent link", "give me a public URL for output.pdf", "publish this one-pager so I can send it", "drop this file somewhere CI can curl it".
Share an agent-generated HTML one-pager (renders in the browser, no login):
bash
share summary.html                                 # hand the printed URL to anyone
Publish a folder of reports, one link each (
share
prints each name + URL):
bash
for f in out/*.html; do share "$f" "reports/$(basename "$f")" "text/html; charset=utf-8"; done
Hand a file to another service / CI job:
bash
URL=$(share model-metrics.json)
本skill可处理的提示词示例:"share this HTML report as a permanent link", "give me a public URL for output.pdf", "publish this one-pager so I can send it", "drop this file somewhere CI can curl it".
分享Agent生成的HTML单页文档(在浏览器中渲染,无需登录):
bash
share summary.html                                 # hand the printed URL to anyone
发布一整个文件夹的报告,每个文件一个链接(
share
会打印每个文件名和对应的URL):
bash
for f in out/*.html; do share "$f" "reports/$(basename "$f")" "text/html; charset=utf-8"; done
把文件交给其他服务/CI任务使用:
bash
URL=$(share model-metrics.json)

elsewhere: curl -sL "$URL" -o metrics.json

elsewhere: curl -sL "$URL" -o metrics.json

undefined
undefined

Gotchas

注意事项

  • Publish wants the blob's storage cluster, not the cluster the upload went through. A teamspace can be bound to compute clusters that store their files under a parent cluster's bucket; publishing with such a compute cluster's id fails with HTTP 500. The artifacts tree listing reports each blob's real
    clusterId
    — always read it from there (the
    share
    function does). Deletes don't take a cluster at all.
  • lightning cp
    needs no cluster flag
    — the server picks the storage. Only if it rejects the upload for a missing cluster does
    cp
    choose one itself (
    LIGHTNING_CLUSTER_ID
    first, which is set inside a Studio, then the teamspace's only or default cloud account) and warn
    No cloud account specified. Using cloud account: <id>.
    Pass
    --cloud-account <id>
    only to steer placement deliberately, and pick a cluster whose
    status.phase
    is
    CLUSTER_STATE_RUNNING
    (
    /v1/projects/$PID/clusters
    ) — bound-but-unusable clusters make the upload fail with a drive error that says nothing about cluster health.
  • Unpublish reports success for links that don't exist.
    DELETE /v1/projects/{pid}/shared-artifacts/{id}
    returns
    HTTP 200
    with
    {}
    for an id that was already revoked or simply mistyped — do not treat exit code 0 as proof; verify by checking the public URL 404s. (
    lightning rm
    , by contrast, fails on a missing path unless you pass
    -f
    .)
  • The served HTML is not byte-identical to what you uploaded. Cloudflare injects a Browser-Insights RUM beacon (
    static.cloudflareinsights.com/beacon.min.js
    ) into HTML responses — a ~350-byte delta. Harmless for viewing, but don't promise a bit-exact document, and don't checksum the response against the source file.
  • Shares are confined to the
    artifacts/
    folder.
    Publish only finds objects under
    projects/{pid}/artifacts/...
    , so the upload must target
    lit://<owner>/<teamspace>/artifacts/...
    . Files under
    uploads/
    or
    lightning_storage/
    are reachable with
    lightning cp
    too, but publish won't find them there.
  • Content-Type is set at publish time, not upload time — the serving handler uses the shared-artifact record's
    contentType
    , overriding the stored object. Set it on the publish call so HTML/PDF render inline.
  • The public link is genuinely open — anyone with it can fetch the file with no auth, and revoking later doesn't recall a link someone already opened. Use
    -F private=true
    for anything you don't want world-readable, and confirm a public one with the user first.
  • -q
    (jq filtering) and the
    share
    /
    shares
    helpers need the
    jq
    binary installed; without it, parse the JSON yourself.
  • The list endpoint is newer than the rest.
    GET /v1/projects/{pid}/shared-artifacts
    returns HTTP 501 "Method Not Allowed" on control planes built before mid-July 2026 — publish/unpublish still work there; only
    shares
    is affected.
  • 发布需要的是blob的存储集群ID,而不是上传经过的集群ID。 一个 teamspace 可以绑定到多个计算集群,这些计算集群的文件存储在父集群的存储桶下;如果使用计算集群的ID进行发布,会返回HTTP 500错误。Artifacts目录列表会返回每个blob的真实
    clusterId
    ——一定要从那里读取(
    share
    函数就是这么做的)。删除操作完全不需要集群ID。
  • lightning cp
    不需要指定集群参数
    ——服务器会自动选择存储位置。只有当服务器因缺少集群而拒绝上传时,
    cp
    才会自己选择一个(优先使用
    LIGHTNING_CLUSTER_ID
    ,Studio中会自动设置这个变量,否则使用teamspace的唯一或默认云账户),并发出警告
    No cloud account specified. Using cloud account: <id>.
    。只有当你需要主动控制存储位置时才传
    --cloud-account <id>
    ,并且要选择
    status.phase
    为
    CLUSTER_STATE_RUNNING
    的集群(可通过
    /v1/projects/$PID/clusters
    查询)——绑定但不可用的集群会导致上传失败,并返回一个完全不提及集群健康状态的驱动器错误。
  • 取消发布对不存在的链接也会返回成功。
    DELETE /v1/projects/{pid}/shared-artifacts/{id}
    对于已经撤销的ID或者打错的ID,会返回
    HTTP 200
    和空对象
    {}
    ——不要把退出码0当作成功的证明;可以通过检查公开URL返回404来验证。(相比之下,
    lightning rm
    在路径不存在时会失败,除非你传了
    -f
    。)
  • 返回的HTML内容和你上传的不是字节完全一致的。 Cloudflare会在HTML响应中注入Browser-Insights RUM信标(
    static.cloudflareinsights.com/beacon.min.js
    )——大约有350字节的差异。对于查看来说没有影响,但不要承诺文件是逐位完全一致的,也不要用响应的校验和与源文件对比。
  • 共享文件仅限于
    artifacts/
    文件夹内。
    发布接口只会查找
    projects/{pid}/artifacts/...
    下的对象,因此上传必须指向
    lit://<owner>/<teamspace>/artifacts/...
    路径。
    uploads/
    或
    lightning_storage/
    下的文件也可以用
    lightning cp
    访问,但发布接口找不到它们。
  • Content-Type是在发布时设置的,而非上传时——服务处理程序使用共享artifact记录中的
    contentType
    ,覆盖存储对象的原有类型。请在发布调用时设置它,这样HTML/PDF才能内联渲染。
  • 公开链接是完全开放的——任何拿到链接的人都可以无需认证获取文件,而且之后撤销链接也无法收回已经被人打开过的文件。对于不想让全世界都能读取的内容,请使用
    -F private=true
    ,并且公开链接一定要先和用户确认。
  • -q
    (jq过滤)和
    share
    /
    shares
    辅助函数需要安装
    jq
    二进制文件;如果没有,请自己解析JSON。
  • 列表接口比其他接口更新。 在2026年7月中旬之前构建的控制平面上,
    GET /v1/projects/{pid}/shared-artifacts
    会返回HTTP 501 "Method Not Allowed"——发布和取消发布功能仍然可用,只有
    shares
    列表功能受影响。