Artifacts Management | Clarifai Docs

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.

• Bash

    pip install --upgrade clarifai
    ```

### Get User ID and PAT

You’ll need the following credentials from the [Clarifai platform](/content/explore/index.html) 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](https://docs.clarifai.com/control/authentication/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`.

- Unix-Like Systems
- Windows

```bash
    export CLARIFAI_PAT=YOUR_PERSONAL_ACCESS_TOKEN_HERE
    ```

```bash
    set CLARIFAI_PAT=YOUR_PERSONAL_ACCESS_TOKEN_HERE
    ```

### Create an App

In the Clarifai platform, [create an app](https://docs.clarifai.com/create/applications/create) where your artifact will be stored. After creating the app, make note of the app ID, as it is required when referencing [artifact paths](https://docs.clarifai.com/create/artifacts/#artifact-resource-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.

- Python SDK

```python
    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

```python
    {
      "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\
              }\
          ]
      }
    }
    ```

- Python SDK
- CLI

```python
    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"
    # )
    ```

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

### Example Output

```python
    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.

- Python SDK
- CLI

```python
    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"
    )
    ```

```bash
    clarifai artifact cp ./model.pt users/user-id/apps/app-id/artifacts/my-artifact --description "Version 2" --visibility=public
    ```

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

- Python SDK
- CLI

```python
    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"
    )
    ```

```bash
    clarifai artifact cp ./model.pt users/user-id/apps/app-id/artifacts/my-artifact/versions/v123
    ```

You can specify an expiration time using [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) format (e.g., `2026-12-31T23:59:59.999Z`)

> **Note:** Artifacts do not expire by default. An artifact version is only deleted if an `expires_at` value is explicitly set at upload time.

- Python SDK
- CLI

```python
    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
    )
    ```

```bash
    clarifai artifact cp ./model.pt users/user-id/apps/app-id/artifacts/my-artifact --expires-at="2026-12-31T23:59:59.999Z"
    ```

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

- CLI

```bash
    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`.

- Python SDK
- CLI

```python
    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}")
    ```

```bash
    clarifai artifact cp users/user-id/apps/app-id/artifacts/my-artifact .
    ```

### Example Output

```python
    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.

- Python SDK
- CLI

```python
    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}")
    ```

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

> **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.
> 
> ```bash
> 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.

- Python SDK
- CLI

```python
    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}")
    ```

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

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

- Python SDK
- CLI

```python
    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}")
    ```

```bash
    clarifai artifact cp users/user-id/apps/app-id/artifacts/my-artifact ./downloads/
    ```

> **Note:** This is how you can use the CLI to download a specific artifact version and save it into an existing local directory.
> 
> ```bash
> 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.

- Python SDK
- CLI

```python
    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)
    ```

```bash
    clarifai artifact list users/user-id/apps/app-id
    ```

### Example Output

```python
    VERSION                           VISIBILITY    EXPIRES_AT           CREATED_AT
    5b359e81aa8f459f866685498a7941cb  PRIVATE       Never                2026-02-11 11:24:06.409811
    8e56238288a24241909a9c92181f4352  PRIVATE       2026-12-31 23:59:59  2026-02-11 11:01:39.273495
    v123                              PRIVATE       Never                2026-02-11 10:51:55.143290
    59e5695cb44d4c47b88d5bb39246e48d  PUBLIC        Never                2026-02-11 10:30:43.724489
    6ec7d79e94434789824c882730df0ad2  PRIVATE       Never                2026-02-11 10:08:25.011732
    ```

You can list all versions of a specific artifact.

- Python SDK
- CLI

```python
    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)
    ```

```bash
    clarifai artifact list users/user-id/apps/app-id/artifacts/my-artifact --versions
    ```

### Example Output

```python
    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.

- Python SDK
- CLI

```python
    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)
    ```

```bash
    clarifai artifact get users/user-id/apps/app-id/artifacts/my-artifact
    ```

### Example Output

```python
    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.

- Python SDK
- CLI

```python
    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)
    ```

```bash
    clarifai artifact get users/user-id/apps/app-id/artifacts/my-artifact/versions/v123
    ```

### Example Output

```python
    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`.

- Python SDK
- CLI

```python
    from clarifai.client.artifact import Artifact

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

```bash
    clarifai artifact delete users/user-id/apps/app-id/artifacts/my-artifact
    ```

### Example Output

```python
    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.

- Python SDK
- CLI

```python
    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()
    ```

```bash
    clarifai artifact delete users/user-id/apps/app-id/artifacts/my-artifact/versions/v123
    ```

### Example Output

```python
    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.

- CLI

```bash
    clarifai artifact delete users/user-id/apps/app-id/artifacts/my-artifact --force
    ```

- [Prerequisites](https://docs.clarifai.com/create/artifacts/manage/#prerequisites)
  - [Install Clarifai Package](https://docs.clarifai.com/create/artifacts/manage/#install-clarifai-package)
  - [Get User ID and PAT](https://docs.clarifai.com/create/artifacts/manage/#get-user-id-and-pat)
  - [Create an App](https://docs.clarifai.com/create/artifacts/manage/#create-an-app)
- [Create an Artifact](https://docs.clarifai.com/create/artifacts/manage/#create-an-artifact)
- [Upload Artifacts](https://docs.clarifai.com/create/artifacts/manage/#upload-artifacts)
- [Download Artifacts](https://docs.clarifai.com/create/artifacts/manage/#download-artifacts)
- [List Artifacts](https://docs.clarifai.com/create/artifacts/manage/#list-artifacts)
- [Get Artifact Details](https://docs.clarifai.com/create/artifacts/manage/#get-artifact-details)
- [Delete Artifacts](https://docs.clarifai.com/create/artifacts/manage/#delete-artifacts)

Build your next AI app, test and tune popular LLMs models, and much more.