lightning-artifacts

Lightning AI Artifacts（永続的に共有できるファイルリンク）

ファイルをチームスペースに公開すると、Lightning にログインしなくても誰でも開ける https://lightning.ai/artifacts/<id> URL を取得できます。コントロールプレーンはリクエストごとにストレージからバイト列をストリーミングするため、署名付き S3 URL とは異なり、リンクは期限切れになりません（約 1 時間の上限もありません）。

一連の操作はすべて CLI のみで行います。 ファイルの操作には lightning cp / ls / rm を使い、公開と非公開化の呼び出しには lightning api を使います。Python や curl は不要です。

セットアップと認証

export DEBUG=0 LIGHTNING_DEBUG=0   # an inherited DEBUG=1 logs the Authorization header; set this in every new shell
# 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
# or: export LIGHTNING_API_KEY=...    # non-interactive alternative (CI, agents)

どちらの認証情報もこのスキル内のすべての呼び出しに使えます。トークンの発行や追加の認証手順は必要ありません。lightning.ai のユーザー／組織の設定からキーを取得するか、lightning api-key create --org <org> --name artifacts を実行してください。キーをハードコードしないでください。環境変数から読み取ってください。本番環境以外のコントロールプレーンを指定するには、LIGHTNING_CLOUD_URL を設定します（デフォルトは https://lightning.ai）。

これはエージェントの現在の環境（プロジェクトの venv、conda 環境など）を使用し、必要に応じてそこにインストールします。その後は、どこでも通常の lightning … を呼び出してください。セットアップが正常に完了しない場合：

症状	対処方法
有効な環境がない、externally-managed-environment が表示される、またはプロジェクト独自のバージョン指定と競合する	個別にインストールします：uv tool install lightning-sdk（または pipx install lightning-sdk）。それが PATH にない場合は "$(uv tool dir --bin)/lightning" を呼び出します
インストール後も Lightning CLI version の行が表示されない	別の lightning（PyTorch Lightning のもの）または無効な環境が優先されています。command -v lightning を確認してから、環境を有効にするか、その環境の bin/lightning を呼び出します
No such command、No such option、または unexpected extra argument	CLI が古すぎます。command -v lightning が示す場所でアップグレードします（uv pip install -U lightning-sdk または uv tool upgrade lightning-sdk）
インストールがブロックされる（環境またはホームディレクトリが読み取り専用、エージェントのサンドボックスなど）	各コマンドを UV_CACHE_DIR="${TMPDIR:-/tmp}/uv" UV_TOOL_DIR="${TMPDIR:-/tmp}/uv-tools" uvx lightning-sdk … として実行します
エージェントのサンドボックス内でのみ、lightning --version を含むすべての呼び出しで SSL/CA エラーが発生する	**/*.pem の読み取り拒否ルールによって certifi の cacert.pem が隠されています。そのパスだけ許可してください。サンドボックスは無効にしないでください
エージェントのサンドボックス内でのみ NameResolutionError が発生する	lightning api も失敗する場合は、ユーザーに lightning.ai と *.lightning.ai（/sandbox）を許可するよう依頼してください。studio／job コマンドまたは SDK のみが失敗する場合、それらはサンドボックスプロキシを経由しません。それらだけサンドボックスの外で実行してください。バックグラウンドのポーラーも同じ理由で、エラーを出さずに失敗します

lightning api のフラグ：-X はメソッド、-f key=val は文字列フィールド、-F key=val は型付きフィールド、-H はヘッダー、--input <file> はリクエストボディ（パイプで渡す場合は --input -）、-q は jq フィルター（-q には jq バイナリが必要）、-i はレスポンスヘッダーを含める指定、--silent は出力なしを指定します。-X を指定せずにフィールドを渡すと、POST リクエストになります。リクエストに --input も含まれる場合、または GET リクエストの場合、フィールドはクエリパラメーターになり、それ以外では POST／ボディ付き PUT の JSON ボディになります。

チームスペースを解決する（最初に行う）

Artifacts はチームスペース（REST API では「プロジェクト」）に保存されます。REST 呼び出しにはオーナー名とプロジェクト ID、lit:// パスにはチームスペース名が必要です。推測しないでください。 複数のメンバーシップが該当し、どれも設定されていない場合は、ユーザーにどれを使うか尋ねてください：

lightning api /v1/memberships -q '.memberships[] | [.name, .projectId, .ownerType, .ownerId] | @tsv'

メンバーシップに含まれるのはオーナーの ID のみです。ownerType を使って名前を解決します：

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 が完全一致するものを選んでください（SDK も同じ方法を使います）。自分のユーザー名で代用しないでください。lit:// パスのオーナーが間違っていると、別のチームスペースにアップロードされます。

組織レベルの権限でアクセスするチームスペースは、/v1/memberships に表示されません。ユーザーが指定したチームスペースが見つからない場合は、<owner>/<teamspace> の組み合わせとプロジェクト ID を尋ねてください。名前で検索しようとしないでください。/v1/projects?name=… は存在しません。

永続的なリンクを公開する（CLI の手順）

公開リンク（private=false。以下の例ではこれがデフォルトです）には、このリクエストでユーザーの許可を得る必要があります。 「これを公開して」や「公開リンクを取得して」は許可を意味するため、再度確認する必要はありません。「チームに送って」は許可を意味しません。リンクで公開される内容を伝えて許可を得るか、-F private=true を使用してください。

3 つの呼び出しを行います。artifacts/ ドライブにアップロードし、保存先のストレージクラスターを読み戻してから、共有アーティファクトとしてオブジェクトを登録します。以下の share と shares には jq バイナリが必要です。ない場合は、自分で JSON を解析してください。

# share <local-file> [remote-name] [content-type]
# 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:
#   ✅ Published report.html (text/html; charset=utf-8)
#   🔗 https://lightning.ai/artifacts/art_...
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. publish needs the blob's storage cluster, read from the listing (see Gotchas)
  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 を単独の行に表示してください。「完了」とだけ伝えてはいけません。 ターミナルではクリックできます。

共有できるのは artifacts/ フォルダー内のファイルに限られます。 公開対象として検索されるのは lit://<owner>/<teamspace>/artifacts/... 以下のオブジェクトのみです。uploads/ や lightning_storage/ 以下のファイルは lightning cp でコピーできますが、公開処理では見つかりません。KEY 変数を使うと、アップロードパスと公開時の filename を同一にできます。filename のみを指定すると、サーバーによって artifacts/ が先頭に追加されますが、両方を明示的に一致させる方法が最も分かりやすいです。

デフォルトの private=false リンクは、認証なしで、リンクを知っている人なら誰でもアクセスできます。 認証済みのプロジェクト閲覧者だけが開けるようにするには、-F private=true を設定してください。

インライン表示されるコンテンツタイプ

公開呼び出し時の contentType によって、HTML/PDF が表示されるか、ダウンロードされるかが決まります。 これはアップロード時ではなく公開時に設定され、リクエストのたびに保存済みオブジェクトのタイプを上書きします。ほとんどの場合、file -b --mime-type で判定できます。拡張子から判別しにくい場合は、タイプを明示してください。

ファイル	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

公開内容の一覧表示、確認、公開解除、削除

lightning ls は、数千件のファイルがあるフォルダーも含め、ドライブ全体を一覧表示します。 サーバーのページを最後までたどります。デフォルトでは 1 階層を表示し、すべてのファイルを表示するには -r を指定します。また、--json を指定すると、size と clusterId を含むエントリーが表示されます。

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"

shares は、プロジェクト内で公開されているリンクをすべて新しい順に一覧表示します。 GET /v1/projects/{pid}/shared-artifacts を呼び出し、id、ファイル名、コンテンツタイプ、公開／非公開、ダウンロード数、URL を返します。

# 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)"'
}

unshare はリンクを無効にしますが、ファイルはドライブに残します。

# 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   # illustrative id; take yours from shares

lightning rm は、クラスター ID を指定せずにファイル自体を削除します。 サーバーは保存場所にかかわらず、そのファイルを削除します。公開解除後、または不要になったアップロードを削除する場合に使用してください。

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 を指定しない場合、フォルダーの削除は拒否されます。

同じ artifacts/<name> に lightning cp を再実行すると、既存のリンクが参照するデータが更新されます。 リンクの ID はそのまま、新しいコンテンツを配信し続けます。同じ filename で公開呼び出しを繰り返すと、新しい ID と URL が作成されます。配信する Content-Type を変更する場合は、こちらを行ってください。

ワークフローの例

このスキルが対応するプロンプト：「この HTML レポートを永続リンクとして共有して」、「output.pdf の公開 URL を教えて」、「この 1 ページの資料を公開して、送れるようにして」、「CI から curl できる場所にこのファイルを置いて」。

エージェントが生成した HTML の 1 ページ資料は、share だけで公開できます。表示された URL は誰でも開けます。

share summary.html                                 # hand the printed URL to anyone

share をループで実行すると、フォルダー内のレポートをそれぞれ 1 つのリンクとして公開できます。

for f in out/*.html; do share "$f" "reports/$(basename "$f")" "text/html; charset=utf-8"; done

share は標準出力に URL のみを表示するため、CI ジョブで URL を取得して curl できます。

URL=$(share model-metrics.json)
# elsewhere:  curl -sL "$URL" -o metrics.json

注意点

• コンピュートクラスターの ID を指定して公開すると HTTP 500 で失敗します。公開には blob のストレージクラスターが必要です。 チームスペースは、親クラスターのバケットにファイルを保存するコンピュートクラスターにバインドされる場合があるため、アップロード先のクラスターがストレージクラスターとは限りません。share と同じように、一覧から実際の clusterId を読み取ってください。
• サーバーがストレージ先を選択するため、lightning cp にクラスターのフラグは不要です。 サーバーがクラスターの指定漏れでアップロードを拒否した場合に限り、cp が自分で選択します（まず LIGHTNING_CLUSTER_ID を使用します。これは Studio 内で設定されます。次に、チームスペースの唯一またはデフォルトのクラウドアカウントを使用します）。その際、No cloud account specified. Using cloud account: <id>. という警告が表示されます。配置先を明示的に指定する場合に限り --cloud-account <id> を渡し、status.phase が CLUSTER_STATE_RUNNING のクラスター（/v1/projects/$PID/clusters）を選んでください。バインドされていても使用できないクラスターでは、クラスターの状態について何も示されないドライブエラーが発生し、アップロードに失敗します。
• unpublish は、存在しないリンクに対しても成功を報告します。 すでに取り消された ID、または入力を間違えた ID に対して DELETE /v1/projects/{pid}/shared-artifacts/{id} を実行すると、HTTP 200 と {} が返されます。終了コード 0 は成功の証明ではありません。公開 URL が 404 になることを確認してください。（一方、lightning rm は -f を指定しない限り、存在しないパスで失敗します。）
• 配信される HTML はアップロードしたファイルとバイト単位で一致しないため、ソースと照合するチェックサムを計算しないでください。 Cloudflare は HTML レスポンスに Browser-Insights RUM ビーコン（static.cloudflareinsights.com/beacon.min.js）を挿入します。表示には問題ありませんが、ビット単位で完全一致するドキュメントだとは保証できません。
• 2026 年 7 月中旬より前に構築されたコントロールプレーンでは、shares は HTTP 501「Method Not Allowed」で失敗します。 一覧エンドポイント GET /v1/projects/{pid}/shared-artifacts は、他のエンドポイントより新しいものです。公開と公開解除は引き続き利用できます。
• 公開リンクは、リンクを知っている人なら誰でもアクセスでき、リンクを取り消しても、すでに取得されたコピーは回収できません。 誰でも読める状態にすべきでないものには -F private=true を使用してください。