> ## Documentation Index > Fetch the complete documentation index at: https://docs.prbe.ai/llms.txt > Use this file to discover all available pages before exploring further. # Artifacts and files > Record files against a run, experiment or project — uploaded or by reference — and read the team's Shared folder. An artifact is a file with an **anchor**. The anchor is what makes artifacts useful rather than a dumping ground: it says which question the file belongs to. ```bash theme={null} probe artifact add $RUN ./ckpt/step-4000.safetensors --kind checkpoint --step 4000 probe artifact add ./dataset.parquet --project folding probe artifact add ./figure.png --experiment dockq ``` | Anchor | Flag | Use it for | | - | - | - | | run | *positional run id* | Checkpoints, outputs, logs, captured code | | experiment | `--experiment` | Something belonging to the question, not one execution | | project | `--project` | Reference material, figures | `--kind` (run anchor only) is one of `checkpoint`, `dataset`, `evaluation`, `code` or `other`; any other word is filed as `other` and kept as its label. Omitted, a `ckpt`, `safetensors`, `pt` or `pth` file is a `checkpoint` and anything else `other`. Workspaces hold projects, never files: the workspace file anchor was retired on 2026-10-17, and a file you add lives on a run, experiment or project. The team's Shared folder (below) takes team datasets only. > [!TIP] > > Data a run trained on, and data a pipeline produced, belongs in the team's [datasets](/tracking/datasets.md): named, versioned and linked to the runs that made and used it. > [!TIP] > > Say what a file is — what produced it, what it shows — in the [notes](/tracking/notes.md) of the run or experiment it belongs to. Files carry no notes of their own. ## Bytes, or a pointer to them Not everything should be uploaded. Probe records three postures, and never silently converts one into another. > **Upload (default)** > > The bytes go to object storage, content-addressed and deduplicated by SHA-256 across runs. Code (`--kind code`, or a word filed as code such as `script`) is always uploaded: `--reference` on code uploads the bytes anyway and says so. > **Reference a local path** > > ```bash theme={null} > probe artifact add $RUN /shared/ckpt/step-4000.pt --reference --hash > ``` > > Records the file's **path** (`file://`) instead of its bytes — for large files on a shared volume the reader can resolve locally. `--hash` reads the whole file to fingerprint it, which enables dedup. `--allow-missing` records a reference even if the path is not visible from this host. > **Reference an object you already store** > > ```bash theme={null} > probe artifact add $RUN --uri s3://my-bucket/ckpt/step-4000.pt --name ckpt/step-4000.pt > ``` > > The pointer and checksum live in Probe; the bytes never leave your bucket. This is what makes air-gapped and data-residency installs work. ## Bulk import ```bash theme={null} probe artifact add $RUN --from-manifest files.jsonl --reference-over 104857600 ``` One JSON object per line, each the row form of the same flags. It is one process, one anchor resolution and N files queued — not N invocations. `--reference-over` records anything at or over that size as a reference instead of uploading it. ## Naming `--name` is the file's **relative path**, defaulting to its basename. Paths are what give the explorer its folder structure, so pass a real one for captured trees: ```bash theme={null} probe artifact add $RUN ./out/figures/loss.png --name figures/loss.png ``` > [!NOTE] > > The file's extension is kept whatever you pass. Say what the file *is* in the run's notes, not by renaming it — a `.json` renamed to `.ckpt` is a file nothing can open. ## Versions ```bash theme={null} probe artifact versions probe artifact version-add --from-artifact # promote another file's bytes, zero-copy probe artifact version-add --uri s3://bucket/ckpt-v2.pt --sha256 --label prod probe artifact pin-impact # which projects and experiments pin these versions probe artifact download --version 2 -o ./v2.pt ``` Versions are a **chain** of immutable, content-addressed versions behind one file. Immutability belongs to the version, so renaming or moving the file never breaks a pin. Appending content identical to the current version is a no-op that returns it, so `version-add` is safe to retry. Run `pin-impact` before deleting anything: it names the work that would break. > [!WARNING] > > Artifacts do **not** supersede by name. Two artifacts with the same name coexist and are ordered newest-first by creation time. A name carried by more than one shared artifact is an error naming both ids, because the duplication the reuse check exists to prevent has already happened and picking one silently would compound it. ## Listing and fetching ```bash theme={null} probe artifact list $RUN probe artifact list --project folding probe artifact tree $RUN --prefix figures/ --limit 50 probe artifact download -o ./local.sif --sha256 ``` `download` streams to the file and checks the bytes against `--sha256` when you pass it (the `content_hash` from `probe artifact list`). A checkpoint folder downloads with `--run RUN --checkpoint best|latest -o DIR`. `tree` returns **one folder level**: the files at that path, plus each child folder with its file count. That is what the dashboard explorer fetches when you expand a folder, so a run with thousands of captured files costs one small answer per folder rather than one enormous answer per run. ## The team's Shared folder One per team, distinct from workspaces, and it never holds projects or experiments. Every member sees everything in it. Since CLI 0.253.0 it holds the team's [datasets](/tracking/datasets.md); its older loose files are **read-only**: listed, downloaded and deleted, never added to. ```bash theme={null} probe shared list probe shared download probe shared delete ``` Adding a file, a new version or a move between a workspace and Shared (`probe shared add`, `share`, `unshare`, `artifact add --workspace|--shared`) is refused with a 410 that says where the file goes now: a team dataset (`probe dataset add`), or a project or run. Shared is also the level artifact **reuse** resolves against — when an agent asks "is there already an official tokenizer for this", it is asking Shared. ## Housekeeping ```bash theme={null} probe artifact move --to project # promote up its own run -> experiment -> project chain probe artifact move --to project --target folding # or name the destination, e.g. another project probe artifact gc-uploads --older-than 2026-10-01T00:00:00Z # sweep uploads that were never confirmed probe artifact delete ``` `move` keeps the file's id. Moving up its own chain needs no `--target`; moving down, or across to another project, does. The server decides which moves it allows and prints its reason when it refuses one. `gc-uploads` only touches abandoned, never-confirmed uploads. Confirmed artifacts are untouched. > [!WARNING] > > `probe artifact delete` is **permanent**. Files do not go to the [trash](/tracking/projects.md#deleting) that holds deleted projects and runs, so there is no restore. It needs a credential with the `delete` scope. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.