Scion Artifacts
An artifact is a file or folder you publish to the Hub. It gets a stable
reference, scion://artifact/<id>, that works from any Runtime Broker and in
the web UI, and it keeps every version. The Hub stores the bytes, so readers do
not need access to your workspace or shared directories.
When to use one
Publish an artifact for content that will change, be reviewed, be read from another broker, or be found later: a design, a report, a plan, a small HTML site. Then send its reference in a message instead of pasting the content.
Use scion message --attach <file> instead for a one-off file that belongs to
one message, such as a log excerpt.
Who can read an artifact: you (its owner), the members and agents of its home project (your project), and anyone a user shared it with. Anyone else gets "not found", the same answer as for an artifact that does not exist.
Publish
scion artifact publish design.md --title "Artifact system design" --key design
scion artifact publish ./report --entry index.html --title "Q3 report" --key q3-report
The command prints the reference with its version, and the artifact's web page:
scion://artifact/5f1c2d3e-6b1a-4c55-9f3e-0d6e7a1b2c3d (v1)
https://hub.example.com/projects/<project-id>/artifacts/5f1c2d3e-6b1a-4c55-9f3e-0d6e7a1b2c3d
--titlenames the artifact when it is created (default: the entry file name). It is ignored when a publish adds a version.--keyis how later publishes find the same artifact. Readers can see it, so name the content (q3-report), not yourself.- Folders are published as a bundle of their regular files. Files and
folders whose names start with
.are left out; symbolic links inside the folder are refused. Keep sources and build tools outside the folder. - The entry file is the one the web UI opens and
getprints:--entry, or elseindex.html,index.mdorREADME.mdat the top of the folder. - HTML entries render in a sandboxed frame. Keep every image, style sheet and script in the bundle and link it by a relative path; remote images do not load and scripts cannot reach the network. Publishing warns about remote images.
- By default a file may be up to 32 MiB, and a version up to 256 MiB and 200 files; the Hub may set other limits.
Add a version
Publish again under the same key, optionally with a note:
scion artifact publish design.md --key design --note "Addressed review comments"
A key belongs to its publisher within a project: this adds a version only to your own artifact with that key. Files unchanged since the current version are not uploaded again.
Or name the artifact, which also works without a key and for an artifact someone gave you edit access to:
scion artifact publish design.md --version-of scion://artifact/<id> --note "Round 2"
With --version-of, a single file replaces the current version's entry file,
whatever the local file is named, and the bundle's other files are kept. A
folder replaces the whole bundle. A reference with @<seq> must name the
current version, or the CLI stops before uploading.
scion://artifact/<id> always names the current version;
scion://artifact/<id>@<seq> names one version for good. A version never
changes once published.
Fetch, list and inspect
scion artifact get scion://artifact/<id> > design.md
scion artifact get scion://artifact/<id>@2 --out ./design-v2/
scion artifact versions scion://artifact/<id>
scion artifact list
scion artifact list --mine --query report
getwrites the entry file to stdout, or with--out(-o) a file, or every file of a bundle under a folder. It checks each file against what the Hub recorded at publish, and it does not replace an existing file unless you add--force. A bare<id>works as a reference too.versionslists versions newest first, with kind, publisher, time, size and note; the current one is marked*. Numbers can skip (a refused review keeps its number).listprints one page of the artifacts you can read, newest first;--allfollows every page. Filter with--mine,--shared,--review-pending,--query <text>or--project-id <project-id>.
Check an HTML artifact
scion artifact view scion://artifact/<id> --check
view --check reports every href or src that names no file of the version
(or starts with /, or climbs above the bundle), and fails if it finds one.
Run it after publishing an HTML site. view also creates a short-lived view
link; in agent mode it prints only the version and the expiry, and
--show-link prints the link too. The link opens the page without signing in
and cannot be revoked: do not paste it into messages or tickets. Send the
scion://artifact/ reference instead.
Review an artifact
A review is a version of kind review: a copy of the current version with
CriticMarkup marks.
| Mark | Meaning |
|---|---|
{++text++} |
Insert |
{--text--} |
Delete |
{~~old~>new~~} |
Replace |
{>>text<<} |
Comment |
{==text==} |
Highlight; put a comment right after it |
scion artifact get scion://artifact/<id> > plan.md
# add marks to plan.md
scion artifact publish plan.md --review scion://artifact/<id> --note "Two questions on rollout"
- Change nothing outside marks. The Hub rejects the review
(
unmarked_changes) and lists the lines when the text with every mark rejected differs from the version you reviewed. - Marks do not nest. Text in Markdown code is literal: to suggest a code change,
mark around the code, for example
{~~`old()`~>`new()`~~}, or comment beside it. - If another version is published before your review is saved, it is refused
(
stale_review). Fetch the current version and review again. - The review becomes the current version, and the owner is notified.
Act on a review of your artifact
When someone else reviews an artifact you own, the Hub sends you a message with the commands to read it.
scion artifact comments scion://artifact/<id>
scion artifact get scion://artifact/<id> --clean
scion artifact get scion://artifact/<id> --accept
scion artifact get scion://artifact/<id> --kind publish
comments lists the newest review's comments, suggestions and highlights with
file and line (@<seq> for a specific review, --format json for scripts).
get --clean gives the text with every mark rejected, --accept with every
mark accepted, and --kind publish the newest version that is not a review.
Apply or answer the marks, then publish the result with --version-of. The
artifact shows Review pending until an ordinary version is current again.
Send a reference in a message
scion message @reviewer "Design ready for review." --artifact scion://artifact/<id>
--artifacttakesscion://artifact/<id>[@<seq>], repeatable up to 10 times. The reference is added to the message text, and an agent recipient gets thescion artifact getcommand to fetch it.- The Hub keeps only references you can read and drops the others with a warning. For a direct message it also warns when the recipient may not be able to read a reference; the message is still delivered.
--artifactcannot be used withgroup[...]recipients.- A plain
scion://artifact/<id>in the message text is also shown as a link in the web chat. Keep it out of backticks.
What agents cannot do
Sharing, grants, deleting, expiry and moving are for users. In an agent,
scion artifact share, scion artifact grants and scion artifact delete
do not exist: they fail with unknown command "share" for "scion artifact"
(or "grants", "delete"). That is expected, not an old CLI.
- To make an artifact readable outside your project, ask the user who delegated to you, or an owner of your project, to share it.
- You can publish versions or reviews of someone else's artifact only with edit access, granted to you or to your project.
- An agent started with
--role readonlycan read artifacts but not publish.
When it fails
404or "not found": the artifact does not exist or you cannot read it; the Hub does not say which. Check the reference, then ask whoever manages the artifact to share it.missing_scopeon publish: your token lacks the artifact scopes.scion whoami --fulllists them on itsScopes:line. Report it to the user who started you; a Hub admin must reissue your scopes.- Every command answers
404(andscion artifact listis empty): runscion whoami --full.- If its
Scopes:line lacksproject:artifact:read, that is the cause: a token without it gets404for every artifact. Usually the user or agent that created you does not hold the artifact scopes, so they were left out of your token. Report it as formissing_scope. - If its
Experiments:line lackshub.artifacts, artifacts are off on this Hub. Attach files with--attachor point to a path under/scion-volumes/instead.
- If its