Skip to main content

Artifacts Management

Create, upload, download, list, get, and delete

Clarifai artifacts are binary, file-based assets associated with your apps — such as model weights, checkpoints, configuration files, or other supporting resources.

You can create, upload, download, list, inspect, and delete artifacts and their versions directly from the command line or using our Python SDK.

Prerequisites​

Install Clarifai Package​

Install the latest version of the clarifai Python package. This also installs the Clarifai Command Line Interface (CLI), which we'll use for running artifact commands.

pip install --upgrade clarifai

Get User ID and PAT​

You’ll need the following credentials from the Clarifai platform for managing artifacts:

  • User ID – In the collapsible left sidebar, select Settings and choose Account from the dropdown list. Then, locate your user ID.

  • Personal Access Token (PAT) – From the same Settings option, choose Secrets to generate or copy your PAT. This token is used to authenticate your connection with the Clarifai platform.

You can then set the PAT as an environment variable using CLARIFAI_PAT.

export CLARIFAI_PAT=YOUR_PERSONAL_ACCESS_TOKEN_HERE

Create an App​

In the Clarifai platform, create an app where your artifact will be stored. After creating the app, make note of the app ID, as it is required when referencing artifact paths in the CLI or SDK.

CLI commands

When using the Clarifai CLI, run clarifai artifact --help to view the complete list of available commands and their descriptions.

Note: You can use af as a shorthand alias for the artifact command. Example: clarifai af --help.

These are the available commands:

  • cp – Upload or download artifact files
  • list (ls) – List artifacts or artifact versions
  • get – Retrieve artifact or version details
  • delete (rm) – Delete artifacts or artifact versions

Create an Artifact​

With the Python SDK, you can create an artifact object under your user and app by specifying an artifact ID. Once created, it enables you to store files as versioned assets and easily upload, track, and manage changes over time.

from clarifai.client.artifact import Artifact

# Initialize and create artifact
artifact = Artifact().create(
    artifact_id="my-artifact",
    user_id="user-id",
    app_id="app-id",
)

# --- Alternative initialization ---
# artifact = Artifact(
#     artifact_id="my-artifact",
#     user_id="user-id",
#     app_id="app-id",
# )
#
# created_artifact = artifact.create()

Upload Artifacts​

You can upload an artifact file by specifying an artifact ID; this automatically creates a new artifact version.

Note: If the artifact does not already exist, it will be created automatically before the upload.

Example Artifact: model.pt
{
  "epoch": 12,
  "loss": 0.0182,
  "model_state_dict": {
      "linear.weight": tensor([...]),
      "linear.bias": tensor([...])
  },
  "optimizer_state_dict": {
      "state": {
          0: {
              "momentum_buffer": tensor([...])
          }
      },
      "param_groups": [
          {
              "lr": 0.001,
              "momentum": 0.9,
              "weight_decay": 0.0005
          }
      ]
  }
}
from clarifai.client.artifact_version import ArtifactVersion

# Upload using direct initialization
version = ArtifactVersion().upload(
    file_path="./model.pt",
    artifact_id="my-artifact",
    user_id="user-id",
    app_id="app-id"
)

# Upload using pre-initialized client
#
# artifact_version = ArtifactVersion(
#     artifact_id="my-artifact",
#     user_id="user-id",
#     app_id="app-id"
# )
#
# version = artifact_version.upload(
#     file_path="./model.pt",
#     description="Latest version"
# )

Example Output
clarifai artifact cp ./model.pt users/alfrick/apps/art-app/artifacts/my-artifact
[INFO] 15:55:48.096696 Uploading file: ./model.pt (421.0 B) |  thread=8674533568 
[INFO] 15:55:49.182076 Artifact my-artifact exists |  thread=8674533568 
Uploading:   0%|                                                               | 0.00/421 [00:00<?, ?B/s][INFO] 15:55:49.232315 Uploading artifact content... |  thread=8674533568 
[INFO] 15:55:49.232857 Upload complete! |  thread=8674533568 
[INFO] 15:55:50.501460 Created artifact version: d392711b340a4b3793b8e0c76379994d |  thread=8674533568 
Uploading: 100%|██████████████████████████████████████████████████████████| 421/421 [00:01<00:00, 300B/s]
[INFO] 15:55:50.632954 Upload completed successfully: d392711b340a4b3793b8e0c76379994d |  thread=8674533568 
Successfully uploaded ./model.pt to users/alfrick/apps/art-app/artifacts/my-artifact
Version ID: d392711b340a4b3793b8e0c76379994d

You can upload with a description and visibility.

Note: These are the visibility options you can set: private (default) restricts access to you, org allows access within your organization, and public makes the artifact accessible to anyone.

from clarifai.client.artifact_version import ArtifactVersion

version = ArtifactVersion().upload(
    file_path="./model.pt",
    artifact_id="my-artifact",
    user_id="user-id",
    app_id="app-id",
    description="Production model v2.0",
    visibility="public",  # Options: "private", "public", "org"
)

You can upload directly to a specific artifact version by providing a version ID.

from clarifai.client.artifact_version import ArtifactVersion

version = ArtifactVersion().upload(
    file_path="./model.pt",
    artifact_id="my-artifact",
    user_id="user-id",
    app_id="app-id",
    version_id="v123"
)

You can specify an expiration time using RFC3339 format (e.g., 2026-12-31T23:59:59.999Z)

Note: If no expires-at value is specified, the artifact version will automatically expire after 7 days by default.

from clarifai.client.artifact_version import ArtifactVersion
from google.protobuf.timestamp_pb2 import Timestamp
import datetime

expires_at = Timestamp()
expires_at.FromDatetime(datetime.datetime(2026, 12, 31, 23, 59, 59))

version = ArtifactVersion().upload(
    file_path="./model.pt",
    artifact_id="my-artifact",
    user_id="user-id",
    app_id="app-id",
    expires_at=expires_at
)

With the CLI, you can use --force or -f to overwrite existing files.

clarifai artifact cp ./model.pt users/user-id/apps/app-id/artifacts/my-artifact --force

Download Artifacts​

You can download the latest artifact version to the current directory.

Note: If no output path is provided, the file is automatically saved to the current working directory using an appropriate filename. When using the SDK, you should specify the version_id.

from clarifai.client.artifact_version import ArtifactVersion

version = ArtifactVersion(
    artifact_id="my-artifact",
    version_id="v123",
    user_id="user-id",
    app_id="app-id"
)

saved_path = version.download()

print(f"Artifact downloaded to: {saved_path}")
Example Output
clarifai artifact cp users/alfrick/apps/art-app/artifacts/my-artifact .
[INFO] 12:03:16.525448 Downloading to ./artifact_v123 |  thread=8416895168 
Downloading: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████| 421/421 [00:00<00:00, 265kB/s]
[INFO] 12:03:18.222105 Download completed: ./artifact_v123 |  thread=8416895168 
Successfully downloaded to ./artifact_v123

You can download the artifact directly to the current directory using a specific filename.

from clarifai.client.artifact_version import ArtifactVersion

version = ArtifactVersion(
    artifact_id="my-artifact",
    version_id="v123",
    user_id="user-id",
    app_id="app-id"
)

saved_path = version.download(
    output_path="./downloaded_model.pt"
)

print(f"Artifact downloaded to: {saved_path}")

# Download using method parameters
# version = ArtifactVersion()
# saved_path = version.download(
#     output_path="./downloaded_model.pt",
#     artifact_id="my-artifact",
#     version_id="v123",
#     user_id="user-id",
#     app_id="app-id"
# )

Note: This is how you can use the CLI to download a specific artifact version and save it as a named file in the current directory. 

clarifai artifact cp users/user-id/apps/app-id/artifacts/my-artifact/versions/v123 ./specific-version.pt

You can use force (or -f for the CLI) to overwrite existing local files.

from clarifai.client.artifact_version import ArtifactVersion

version = ArtifactVersion(
    artifact_id="my-artifact",
    version_id="v123",
    user_id="user-id",
    app_id="app-id"
)

saved_path = version.download(
    output_path="./downloaded_model.pt",
    force=True
)

print(f"Artifact downloaded to: {saved_path}")

You can download the latest artifact version by specifying an already existing local destination directory.

from clarifai.client.artifact_version import ArtifactVersion

version = ArtifactVersion(
    artifact_id="my-artifact",
    version_id="v123",
    user_id="user-id",
    app_id="app-id"
)

# The directory must already exist
saved_path = version.download(
    output_path="./downloads/"
)

print(f"Artifact downloaded to: {saved_path}")

Note: This is how you can use the CLI to download a specific artifact version and save it into an existing local directory. 

clarifai artifact cp users/user-id/apps/app-id/artifacts/my-artifact/versions/v123 /tmp/

List Artifacts​

You can list all artifacts within your app.

Note: When using the CLI, you can use ls as a shorthand alias for the list command.

from clarifai.client.artifact import Artifact

artifact_client = Artifact()

for artifact_pb in artifact_client.list(user_id="user-id", app_id="app-id"):
    print(f"Artifact ID: {artifact_pb.id}")

    # Uncomment the line below to print the full artifact protobuf details
    # print(artifact_pb)
Example Output
clarifai artifact list users/alfrick/apps/art-app
ARTIFACT     LATEST_VERSION                    CREATED_AT
my-artifact  8bf6bf7ad21a452cb5a7b4f141a46b2a  2026-02-03 15:02:31.319386

You can list all versions of a specific artifact.

from clarifai.client.artifact_version import ArtifactVersion

artifact_versions = ArtifactVersion(
    artifact_id="my-artifact",
    user_id="user-id",
    app_id="app-id"
)

for version_pb in artifact_versions.list():
    print(f"Version ID: {version_pb.id}")
    print(f"Description: {version_pb.description}")
    print(f"Visibility: {version_pb.visibility.gettable}")
    print("-" * 40)
Example Output
clarifai artifact list users/alfrick/apps/art-app/artifacts/my-artifact --versions
VERSION                           VISIBILITY    EXPIRES_AT                  CREATED_AT
8bf6bf7ad21a452cb5a7b4f141a46b2a  PRIVATE       Never                       2026-02-10 13:55:00.326134
1213897c183043f3abd610e747350c37  PRIVATE       2026-12-31 23:59:59.999000  2026-02-10 13:46:05.553821
v123                              PRIVATE       Never                       2026-02-10 13:27:39.009518
e262703f909f4b57b4105fb64d2426ad  PUBLIC        Never                       2026-02-10 13:14:39.157667

Get Artifact Details​

You can get the details of a specific artifact.

from clarifai.client.artifact import Artifact

artifact = Artifact(
    artifact_id="my-artifact",
    user_id="user-id",
    app_id="app-id"
)
artifact_info = artifact.get()

print(artifact_info)
Example Output
clarifai artifact get users/alfrick/apps/art-app/artifacts/my-artifact
Artifact ID: my-artifact
Latest version: fe71b81c8e984e56a2fd012be608f90b
Created at: 2026-02-03 15:02:31.319386
Modified at: 2026-02-10 19:48:45.005023

You can get the details of a specific artifact version.

from clarifai.client.artifact_version import ArtifactVersion

version = ArtifactVersion(
    artifact_id="my-artifact",
    version_id="v123", 
    user_id="user-id",
    app_id="app-id"
)
version_info = version.get()

print(version_info)
Example Output
clarifai artifact get users/alfrick/apps/art-app/artifacts/my-artifact/versions/v123
Artifact Version: v123
Description: N/A
Visibility: PRIVATE
Expires at: Never
Created at: 2026-02-10 13:27:39.009518
Modified at: 2026-02-10 13:27:39.224791

Delete Artifacts​

You can delete an artifact (including all versions) by specifying its artifact_id.

Note: When using the CLI, you can use rm as a shorthand alias for the delete command.

from clarifai.client.artifact import Artifact

artifact = Artifact(
    artifact_id="my-artifact",
    user_id="user-id",
    app_id="app-id"
)
artifact.delete()
Example Output
clarifai artifact delete users/alfrick/apps/art-app/artifacts/my-artifact
Are you sure you want to delete artifact 'my-artifact'? [y/N]: y
Successfully deleted artifact my-artifact

You can delete a specific artifact version by including its version ID.

from clarifai.client.artifact_version import ArtifactVersion

version = ArtifactVersion(
    artifact_id="my-artifact",
    version_id="v123", 
    user_id="user-id",
    app_id="app-id"
)
version.delete()
Example Output
clarifai artifact delete users/alfrick/apps/art-app/artifacts/my-artifact/versions/v123
Are you sure you want to delete artifact version 'v123'? [y/N]: y
Successfully deleted artifact version v123

With the CLI, you can use --force or -f to delete without a confirmation prompt.

clarifai artifact delete users/user-id/apps/app-id/artifacts/my-artifact --force
© 2026 Clarifai, Inc. All rights reserved